sandbox-provider 0.1.1

data/lib/sandbox/provider/daytona.rb

@@ -0,0 +1,272 @@
+# Daytona linux-vm sandboxes: one VM snapshot per shape and region. SSH lands as root behind a short-lived token.
+class Sandbox::Provider::Daytona < Sandbox::Adapter::SandboxVm
+  IMAGE = "ubuntu:24.04"
+  REGION = "uk-south-1"
+  # By the state string the API answers.
+  STATES = {
+    "started" => :running,
+    "stopped" => :stopped,
+    "archived" => :stopped,
+    "error" => :broken,
+    "build_failed" => :broken,
+    "destroyed" => :broken
+  }.freeze
+  TOKEN_MINUTES = 24 * 60
+  # An SSH token and where it lands, good until `until`.
+  Access = Data.define(:host, :port, :token, :until)
+  # One token per sandbox, kept until it nears expiry: minting a new one revokes the previous, so every
+  # transport to the same sandbox (root or the deploy user) shares it. A fork gets its own.
+  TOKENS = {}
+  TOKENS_LOCK = Mutex.new
+
+  def initialize(token, client: Client.new(token), **)
+    super(token, **)
+    @client = client
+  end
+
+  # The VM snapshot sandboxes are created from, in this region at this size: made once per organization,
+  # asked for by name. A failed one raises with its reason.
+  def prepare(shape = default_shape, disk = default_disk(shape))
+    cpu, memory = shape.split("x").map(&:to_i)
+    size = { cpu:, memory:, disk: }
+    digest = Digest::SHA256.hexdigest("#{IMAGE}|#{size.values.join("|")}|#{REGION}")
+    name = "nvoi-vm-#{digest[0, 8]}"
+    loop do
+      snapshot = @client.find("/snapshots/#{name}")
+      case snapshot&.dig(:state)
+      when "active" then return name
+      when nil
+        @client.post(
+          "/snapshots",
+          { name:, imageName: IMAGE, sandboxClass: "linux-vm", **size, regionId: REGION },
+          again: false
+        )
+      when "error", "build_failed" then raise Error, "snapshot #{name}: #{snapshot[:errorReason]}"
+      else sleep 5
+      end
+    end
+  end
+
+  LADDER = %w[2x4 4x8 8x16 16x32].freeze
+  DISK = { min: 10, step: 5, default: 10 }.freeze
+
+  # The ladder within the org's per-sandbox limits for this region and class, priced by the formula; disk
+  # floats up to the limit.
+  def shapes
+    max = limits
+    as_of = price_table.as_of("daytona")
+    LADDER.filter_map do |key|
+      cpu, memory = key.split("x").map(&:to_i)
+      next if cpu > max[:cpu] || memory > max[:memory]
+      disk = DISK.merge(max: max[:disk])
+      [ key, Sandbox::Adapter.shape(cpu:, memory:, disk:, rate: formula(cpu, memory, DISK[:default]),
+                           held: disk_rate(DISK[:default]), source: :formula, as_of:) ]
+    end.to_h
+  end
+
+  def rate(key, disk: nil)
+    cpu, memory = key.split("x").map(&:to_i)
+    formula(cpu, memory, disk || DISK[:default])
+  end
+
+  def held(_key, disk: nil) = disk_rate(disk || DISK[:default])
+
+  PRICING = "https://www.daytona.io/pricing".freeze
+
+  # Their pricing page: three hourly rates, per vCPU, per GiB of memory, per GiB of storage.
+  def prices(page = Sandbox::Adapter::Pages.fetch(PRICING))
+    vcpu = page[%r{vCPU\s*\$(\d+\.\d+)/h}, 1]
+    gib = page[%r{Memory\s+GiB\s*\$(\d+\.\d+)/h}, 1]
+    disk = page[%r{Storage\s+GiB\s*\$(\d+\.\d+)/h}, 1]
+    return { source: "page", rates: nil } unless vcpu && gib && disk
+    { source: "page", rates: { "vcpu_hour" => Sandbox::Adapter::Pages.cents(vcpu), "gib_hour" => Sandbox::Adapter::Pages.cents(gib),
+                               "disk_gib_hour" => Sandbox::Adapter::Pages.cents(disk) } }
+  end
+
+  # Their meter since creation, from the analytics periods: the ones with cpu are running time, the rest
+  # is disk while stopped; every period is priced.
+  def usage(m)
+    from = m.data[:createdAt].presence || "2020-01-01T00:00:00Z"
+    periods = @client.analytics("/organization/#{org_id}/sandbox/#{m.id}/usage",
+                                { from: Time.iso8601(from).utc.iso8601,
+to: Time.current.utc.iso8601 })
+    running = periods.select { _1[:cpu].to_i.positive? }
+    {
+      seconds: running.sum { (Time.iso8601(_1[:endAt]) - Time.iso8601(_1[:startAt])).round },
+      cents: periods.sum { _1[:price].to_f * 100 }.round(4)
+    }
+  end
+
+  # Ours alone: the org may be shared, and a sandbox of ours carries an nvoi- label from create or fork.
+  def list
+    sandboxes.select { |s| (s[:labels] || {}).keys.any? {
+ _1.to_s.start_with?("nvoi-") } }.map { machine(_1) }
+  end
+
+  # autoStopInterval is a net for a dead control plane; the app's own timers stop boxes sooner. Never retried:
+  # a retry would orphan a VM.
+  def create(name, labels: {}, shape: default_shape, disk: default_disk(shape), **)
+    sandbox = @client.find("/sandbox/#{name}") || @client.post(
+      "/sandbox",
+      {
+        name:,
+        snapshot: prepare(shape, disk),
+        target: REGION,
+        labels:,
+        autoStopInterval: 60,
+        autoDeleteInterval: -1
+      },
+      again: false
+    )
+    wake(machine(sandbox))
+  end
+
+  def find(name)
+    sandbox = @client.find("/sandbox/#{name}") or return nil
+    machine(sandbox)
+  end
+
+  def wake(m)
+    current = wait(m.id) { |s| %w[started stopped error build_failed destroyed].include?(s) }
+    if current[:state] == "stopped"
+      @client.post("/sandbox/#{m.id}/start")
+      current = wait(m.id) { |s| %w[started error].include?(s) }
+    end
+    unless current[:state] == "started"
+      raise Error, "sandbox #{m.name} #{current[:state]}: #{current[:errorReason]}"
+    end
+    machine(current)
+  end
+
+  def halt(m)
+    sandbox = @client.find("/sandbox/#{m.id}")
+    return false if sandbox.nil? || sandbox[:state] == "destroyed"
+    unless %w[stopped stopping].include?(sandbox[:state])
+      @client.post("/sandbox/#{m.id}/stop")
+      wait(m.id) { |s| s == "stopped" }
+    end
+    true
+  end
+
+  # A parent with live forks cannot go: the error says so.
+  def destroy(m)
+    TOKENS_LOCK.synchronize { TOKENS.delete(m.id) }
+    @client.delete("/sandbox/#{m.id}", force: true)
+  rescue Error => e
+    raise unless e.status == 404
+  end
+
+  # A copy of a started parent, disk and memory. A name already taken is the copy from a previous attempt.
+  def fork(m, name, labels: {}, shape: nil, disk: nil)
+    sandbox = @client.find("/sandbox/#{name}") ||
+      @client.post("/sandbox/#{m.id}/fork", { name: }, again: false)
+    @client.put("/sandbox/#{sandbox[:id]}/labels", { labels: }) if labels.any?
+    wake(machine(sandbox))
+  end
+
+  def transport(m, key: nil, host_key: nil, on_host_key: nil)
+    access = TOKENS_LOCK.synchronize do
+      kept = TOKENS[m.id]
+      kept = nil if kept.nil? || kept.until < Time.current
+      kept || (TOKENS[m.id] = mint(m.id))
+    end
+    Sandbox::Adapter::Ssh.new(
+      host: access.host,
+      port: access.port,
+      user: access.token,
+      key: nil,
+      host_key:,
+      on_host_key:
+    )
+  end
+
+  # Their preview link for the port: a host at their edge and a token it wants in a header. The token rotates
+  # across a park, so nothing keeps it. A sandbox that is not there answers 404, which is nothing to proxy to.
+  def preview(m, port)
+    body = @client.find("/sandbox/#{m.id}/ports/#{port}/preview-url") or return nil
+    url, token = body.values_at(:url, :token)
+    if url.blank? || token.blank?
+      raise Error, "sandbox #{m.id} answered half a preview for port #{port}"
+    end
+
+    uri = URI(url)
+    {
+      host: [ uri.host, (uri.port unless uri.port == uri.default_port) ].compact.join(":"),
+      scheme: uri.scheme,
+      token:,
+      # Without the second one, the first response is their interstitial warning page.
+      headers: { "x-daytona-preview-token" => token, "x-daytona-skip-preview-warning" => "true" }
+    }
+  end
+
+  private
+
+    def formula(cpu, memory, disk)
+      (cpu * cents("vcpu_hour") + memory * cents("gib_hour") + disk_rate(disk)).round(6)
+    end
+
+    def cents(key) = price_table.cents("daytona", key)
+
+    def disk_rate(disk) = (disk * cents("disk_gib_hour")).round(6)
+
+    # The list, an array or paged under items.
+    def sandboxes
+      body = @client.get("/sandbox")
+      body.is_a?(Hash) ? body[:items] : body
+    end
+
+    # The org: a setting, or read off any sandbox; there is no endpoint for it under an API key.
+    def org_id
+      @org_id ||= Sandbox::Adapter.credentials.setting(:daytona_org_id) ||
+        sandboxes.first&.dig(:organizationId) or
+        raise Error, "daytona: no sandbox to read the organization from"
+    end
+
+    # The org's ceiling per sandbox in this region and class; the ladder's top when it says nothing.
+    def limits
+      region = @client.get("/organizations/#{org_id}/usage")[:regionUsage]
+                      .find { _1[:regionId] == REGION && _1[:sandboxClass] == "linux-vm" }
+      { cpu: region&.dig(:maxCpuPerSandbox) || 16, memory: region&.dig(:maxMemoryPerSandbox) || 32,
+        disk: region&.dig(:maxDiskPerSandbox) || 15 }
+    rescue Error
+      # The ladder's top stands in when the org says nothing; a size it refuses fails at create with
+      # their own reason.
+      { cpu: 16, memory: 32, disk: 15 }
+    end
+
+    def mint(sandbox_id)
+      access = @client.post(
+        "/sandbox/#{sandbox_id}/ssh-access",
+        {},
+        params: { expiresInMinutes: TOKEN_MINUTES }
+      )
+      command = access[:sshCommand].to_s
+      Access.new(
+        host: command[/@(\S+)/, 1],
+        port: (command[/-p (\d+)/, 1] || 22).to_i,
+        token: access[:token],
+        until: Time.current + (TOKEN_MINUTES - 10).minutes
+      )
+    end
+
+    def wait(id, timeout: 300)
+      deadline = Time.current + timeout
+      loop do
+        sandbox = @client.get("/sandbox/#{id}")
+        return sandbox if yield(sandbox[:state])
+        if Time.current > deadline
+          raise Error, "sandbox #{id} still #{sandbox[:state]} after #{timeout}s"
+        end
+        sleep 3
+      end
+    end
+
+    def machine(sandbox)
+      Sandbox::Adapter::Machine.new(
+        id: sandbox[:id],
+        name: sandbox[:name],
+        state: STATES.fetch(sandbox[:state], :starting),
+        data: sandbox
+      )
+    end
+end

data/lib/sandbox/provider/e2b/client.rb

@@ -0,0 +1,52 @@
+require "net/http"
+
+# Thin JSON client for https://api.e2b.dev. Raises Sandbox::Adapter::Provider::Error on non-2xx; 404 reads as nil where
+# a lookup is meant. Every body comes back symbol-keyed.
+class Sandbox::Provider::E2b::Client
+  BASE = "https://api.e2b.dev"
+
+  def initialize(token)
+    @token = token
+  end
+
+  def get(path, params = {}) = request(Net::HTTP::Get, path, params:)
+  def post(path, body = {}) = request(Net::HTTP::Post, path, body:)
+  def delete(path) = request(Net::HTTP::Delete, path)
+
+  def find(path)
+    get(path)
+  rescue Sandbox::Adapter::Provider::Error => e
+    raise unless e.status == 404
+    nil
+  end
+
+  private
+
+    def request(klass, path, params: {}, body: nil)
+      uri = URI("#{BASE}#{path}")
+      uri.query = URI.encode_www_form(params) if params.any?
+      req = klass.new(uri)
+      req["X-API-Key"] = @token
+      req["Content-Type"] = "application/json"
+      req.body = body.to_json if body
+      res = Sandbox::Adapter::Provider.reaching("e2b") do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 120) do |http|
+          http.request(req)
+        end
+      end
+      json = res.body.to_s.empty? ? {} : parse(res.body)
+      return json if res.is_a?(Net::HTTPSuccess)
+      detail = json.is_a?(Hash) ? json[:message] : json.to_s[0, 200]
+      raise Sandbox::Adapter::Provider::Error.new(
+        "e2b #{req.method} #{path} #{res.code}: #{detail}",
+        status: res.code.to_i
+      )
+    end
+
+    # Symbol-keyed; a body that is not JSON is kept as text for the error.
+    def parse(body)
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      body
+    end
+end

data/lib/sandbox/provider/e2b/envd.rb

@@ -0,0 +1,121 @@
+require "net/http"
+
+# Reaches an E2B sandbox through envd, its in-box daemon: Connect-RPC for processes (streamed, so a long command
+# is followed as it runs) and the files endpoint for uploads and downloads. Everything runs as root; Box's
+# `as` handles the rest. What E2B hands Sandbox::Adapter::Box.
+class Sandbox::Provider::E2b::Envd
+  HOST = "https://sandbox.e2b.app"
+  PORT = "49983"
+  END_FLAG = 2
+  CONNECTION_ERRORS = [
+    Errno::ECONNREFUSED,
+    Errno::ECONNRESET,
+    Errno::ETIMEDOUT,
+    Errno::EPIPE,
+    Net::OpenTimeout,
+    Net::ReadTimeout,
+    SocketError,
+    IOError
+  ].freeze
+
+  def initialize(sandbox_id, access_token, user: "root")
+    @sandbox_id = sandbox_id
+    @access_token = access_token
+    @user = user
+  end
+
+  def address = @sandbox_id
+  def connection_errors = CONNECTION_ERRORS
+  # Following a detached command through a second request does not hold up; a command is one streamed request.
+  def reattaches? = false
+
+  # Runs a shell command line; each output line is yielded as it arrives; returns the exit status.
+  def exec(command)
+    status = nil
+    buffers = Hash.new { |h, k| h[k] = "".b }
+    start = { process: { cmd: "/bin/bash", args: [ "-c", command ] } }
+    frames("process.Process/Start", start) do |frame|
+      event = frame.dig(:result, :event) || frame[:event] || {}
+      %i[stdout stderr].each do |stream|
+        data = event.dig(:data, stream) or next
+        Sandbox::Adapter::Box.each_line(buffers[stream], data.unpack1("m0")) { |line| yield line if block_given? }
+      end
+      status = event.dig(:end, :exitCode).to_i if event[:end]
+    end
+    buffers.each_value do |rest|
+      yield rest.force_encoding("UTF-8").scrub if rest.present? && block_given?
+    end
+    status
+  end
+
+  def upload(path, io)
+    uri = URI("#{HOST}/files?path=#{CGI.escape(path)}&username=#{@user}")
+    req = Net::HTTP::Post.new(uri)
+    headers.each { |k, v| req[k] = v }
+    req.set_form([ [ "file", io, { filename: File.basename(path) } ] ], "multipart/form-data")
+    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 600) do |http|
+      http.request(req)
+    end
+    unless res.is_a?(Net::HTTPSuccess)
+      raise Sandbox::Adapter::Box::Failed, "envd upload #{path}: #{res.code} #{res.body.to_s[0, 200]}"
+    end
+  end
+
+  def download(path)
+    uri = URI("#{HOST}/files?path=#{CGI.escape(path)}&username=#{@user}")
+    req = Net::HTTP::Get.new(uri)
+    headers.each { |k, v| req[k] = v }
+    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 600) do |http|
+      http.request(req)
+    end
+    unless res.is_a?(Net::HTTPSuccess)
+      raise Sandbox::Adapter::Box::Failed, "envd download #{path}: #{res.code} #{res.body.to_s[0, 200]}"
+    end
+    res.body
+  end
+
+  private
+
+    def headers
+      {
+        "E2b-Sandbox-Id" => @sandbox_id,
+        "E2b-Sandbox-Port" => PORT,
+        "X-Access-Token" => @access_token.to_s,
+        "Authorization" => "Basic #{Base64.strict_encode64("#{@user}:")}"
+      }
+    end
+
+    # A Connect stream: 5-byte envelopes, the last one flagged, read as the body arrives; each frame is yielded
+    # symbol-keyed.
+    def frames(method, body)
+      uri = URI("#{HOST}/#{method}")
+      req = Net::HTTP::Post.new(uri)
+      connect = {
+        "Connect-Protocol-Version" => "1",
+        "Content-Type" => "application/connect+json",
+        "Connect-Timeout-Ms" => (24 * 3600 * 1000).to_s
+      }
+      headers.merge(connect).each { |k, v| req[k] = v }
+      payload = JSON.dump(body)
+      req.body = [ 0 ].pack("C") + [ payload.bytesize ].pack("N") + payload
+      Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 24 * 3600) do |http|
+        http.request(req) do |res|
+          unless res.is_a?(Net::HTTPSuccess)
+            raise Sandbox::Adapter::Box::Failed, "envd #{method}: #{res.code} #{res.body.to_s[0, 200]}"
+          end
+          pending = "".b
+          res.read_body do |chunk|
+            pending << chunk.b
+            while pending.bytesize >= 5
+              flags, length = pending.unpack("CN")
+              break if pending.bytesize < 5 + length
+              frame = pending.byteslice(5, length)
+              pending = pending.byteslice(5 + length..) || "".b
+              return if flags & END_FLAG != 0
+              yield JSON.parse(frame, symbolize_names: true)
+            end
+          end
+        end
+      end
+    end
+end

data/lib/sandbox/provider/e2b.rb

@@ -0,0 +1,222 @@
+# E2B sandboxes: one template per shape (a base image with docker), sandboxes named through their metadata.
+# No SSH: Box talks to envd, the daemon in the sandbox, as root.
+class Sandbox::Provider::E2b < Sandbox::Adapter::SandboxVm
+  IMAGE = "ubuntu:24.04"
+  # Seconds a sandbox may run before E2B pauses it on its own; the app's own timers pause boxes sooner.
+  TIMEOUT = 3600
+  # By the state string the API answers.
+  STATES = { "running" => :running, "paused" => :stopped }.freeze
+  # The metadata key carrying the name.
+  LABEL = :"nvoi-name"
+  # Where a sandbox's ports are served, unless the sandbox names another domain.
+  DOMAIN = "e2b.app".freeze
+  # A fork inherits its parent's metadata and can take none of its own, so the name a sandbox answers to is
+  # written inside it; a running sandbox is asked, a paused one is not woken for it.
+  MARKER = "/etc/nvoi-name"
+  LADDER = %w[2x4 4x8 8x16 16x32].freeze
+  # The plan's ceiling per sandbox; there is no endpoint for it.
+  LIMITS = { cpu: 8, memory: 8, disk: 20 }.freeze
+  DISK = { min: 10, max: LIMITS[:disk], step: 5, default: 10 }.freeze
+  ENDED = %w[sandbox.lifecycle.paused sandbox.lifecycle.killed].freeze
+
+  def initialize(token, client: Client.new(token), **)
+    super(token, **)
+    @client = client
+  end
+
+  # What the template build runs on the image, as root (builds run as "user" by default): the tools the first
+  # steps need, and docker. No init runs in a sandbox, so dockerd and the app are started by the steps themselves.
+  BUILD = [
+    { type: "USER", args: [ "root" ] },
+    {
+      type: "RUN",
+      args: [
+        "apt-get update -qq && " \
+        "DEBIAN_FRONTEND=noninteractive apt-get install -y -qq curl ca-certificates gnupg git sudo"
+      ]
+    },
+    { type: "RUN", args: [ "curl -fsSL https://get.docker.com | sh" ] }
+  ].freeze
+
+  # The template sandboxes are made from, at this size; built once per team, named by what goes in.
+  def prepare(shape = default_shape, disk = default_disk(shape))
+    cpu, memory = shape.split("x").map(&:to_i)
+    digest = Digest::SHA256.hexdigest("#{IMAGE}|#{cpu}|#{memory}|#{disk}|#{BUILD.to_json}")
+    name = "nvoi-#{digest[0, 8]}"
+    found = @client.get("/templates").find { |t| Array(t[:aliases]).include?(name) }
+    return found[:templateID] if found
+
+    built = @client.post(
+      "/v3/templates",
+      {
+        name:,
+        cpuCount: cpu,
+        memoryMB: memory * 1024,
+        minFreeDiskMb: disk * 1024
+      }
+    )
+    @client.post("/v2/templates/#{built[:templateID]}/builds/#{built[:buildID]}", {
+      fromImage: IMAGE,
+      steps: BUILD
+    })
+    deadline = Time.current + 1800
+    loop do
+      status = @client.get("/templates/#{built[:templateID]}/builds/#{built[:buildID]}/status")
+      return built[:templateID] if status[:status] == "ready"
+      raise Error, "template #{name}: #{status[:reason]}" if status[:status] == "error"
+      raise Error, "template #{name} still building after 30 minutes" if Time.current > deadline
+      sleep 10
+    end
+  end
+
+  # The ladder within the plan's limit, priced by the formula; storage is free, so held is zero.
+  def shapes
+    as_of = price_table.as_of("e2b")
+    LADDER.filter_map do |key|
+      cpu, memory = key.split("x").map(&:to_i)
+      next if cpu > LIMITS[:cpu] || memory > LIMITS[:memory]
+      [ key,
+Sandbox::Adapter.shape(cpu:, memory:, disk: DISK, rate: formula(cpu, memory), source: :formula, as_of:) ]
+    end.to_h
+  end
+
+  def rate(key, disk: nil)
+    cpu, memory = key.split("x").map(&:to_i)
+    formula(cpu, memory)
+  end
+
+  def held(_key, disk: nil) = 0.0
+
+  PRICING = "https://e2b.dev/pricing".freeze
+
+  # Their pricing page: two per-second rates, the first row of the vCPU table and of the memory table.
+  def prices(page = Sandbox::Adapter::Pages.fetch(PRICING))
+    vcpu = page[%r{vCPUs\s+Plan\s+Costs\s+1\s+[\w /]+\$(\d+\.\d+)/s}, 1]
+    gib = page[%r{Memory \(GiB\)\s+Plan\s+Costs\s+1\s+[\w /]+\$(\d+\.\d+)/s}, 1]
+    return { source: "page", rates: nil } unless vcpu && gib
+    { source: "page", rates: { "vcpu_hour" => Sandbox::Adapter::Pages.cents(vcpu, per: 3600),
+                               "gib_hour" => Sandbox::Adapter::Pages.cents(gib, per: 3600) } }
+  end
+
+  # Their meter: each pause or kill event carries the execution it ended, so the sum is the running time
+  # up to the last stop; a run underway is not in it yet. Events are kept seven days. No price.
+  def usage(m)
+    events = @client.get("/events/sandboxes/#{m.id}", { limit: 100 })
+    ended = events.select { ENDED.include?(_1[:type]) }
+    { seconds: (ended.sum {
+ _1.dig(:eventData, :execution, :execution_time).to_f } / 1000).round, cents: nil }
+  end
+
+  # Every sandbox with our label, named by it; a fork shares its parent's, which is the name it was made
+  # under and enough for a sweep.
+  def list
+    @client.get("/v2/sandboxes").filter_map do |s|
+      name = s.dig(:metadata, LABEL) or next
+      machine(s, name)
+    end
+  end
+
+  def create(name, labels: {}, shape: default_shape, disk: default_disk(shape), **)
+    find(name) || begin
+      data = @client.post(
+        "/sandboxes",
+        {
+          templateID: prepare(shape, disk),
+          timeout: TIMEOUT,
+          autoPause: true,
+          metadata: labels.merge(LABEL => name)
+        }
+      )
+      named(machine(data, name))
+    end
+  end
+
+  # Every sandbox of ours is a candidate, since a fork carries its parent's metadata: a running one is asked its
+  # name; a paused one counts only when its own metadata says so (a seed, never a fork).
+  def find(name)
+    ours = @client.get("/v2/sandboxes").select do |s|
+      s.dig(:metadata, LABEL) && %w[running paused].include?(s[:state])
+    end
+    data = ours.find { |s| s[:state] == "running" && marker(machine(s, name)) == name } ||
+      ours.find do |s|
+        s[:state] == "paused" && s.dig(:metadata, LABEL) == name &&
+          ours.none? { |o| o[:state] == "paused" && o[:parent] == s[:sandboxID] }
+      end
+    data && machine(data, name)
+  end
+
+  # Connect resumes a paused sandbox and refreshes the timeout on a running one.
+  def wake(m) = machine(@client.post("/sandboxes/#{m.id}/connect", { timeout: TIMEOUT }), m.name)
+
+  def halt(m)
+    @client.post("/sandboxes/#{m.id}/pause")
+    true
+  rescue Error => e
+    raise unless [ 404, 409 ].include?(e.status)
+    e.status == 409
+  end
+
+  def destroy(m)
+    @client.delete("/sandboxes/#{m.id}")
+  rescue Error => e
+    raise unless e.status == 404
+  end
+
+  # A copy of a running parent, disk and memory, given its own name inside.
+  def fork(m, name, labels: {}, shape: nil, disk: nil)
+    find(name) || begin
+      result = @client.post("/sandboxes/#{m.id}/fork", { timeout: TIMEOUT, count: 1 }).first
+      raise Error, "fork of #{m.name}: #{result.dig(:error, :message)}" if result[:error]
+      named(machine(result[:sandbox], name))
+    end
+  end
+
+  def transport(m, key: nil, host_key: nil, on_host_key: nil)
+    data = m.data
+    unless data[:envdAccessToken]
+      data = @client.post("/sandboxes/#{m.id}/connect", { timeout: TIMEOUT })
+    end
+    Envd.new(m.id, data[:envdAccessToken])
+  end
+
+  # Their host for the port, TLS at their edge. Sandboxes are made with public traffic allowed, so no token
+  # goes with it; a restricted one would carry `trafficAccessToken` as `e2b-traffic-access-token`. A paused
+  # sandbox is nothing to proxy to; asking about it does not wake it.
+  def preview(m, port)
+    data = @client.find("/sandboxes/#{m.id}") or return nil
+    return nil unless data[:state] == "running"
+
+    host = "#{port}-#{m.id}.#{data[:domain].presence || DOMAIN}"
+    { host:, scheme: "https", token: nil, headers: {} }
+  end
+
+  private
+
+    def formula(cpu, memory)
+      (cpu * cents("vcpu_hour") + memory * cents("gib_hour")).round(6)
+    end
+
+    def cents(key) = price_table.cents("e2b", key)
+
+    def named(m)
+      transport(m).exec("printf '%s' #{Shellwords.escape(m.name)} > #{MARKER}")
+      m
+    end
+
+    def marker(m)
+      out = +""
+      transport(m).exec("cat #{MARKER} 2>/dev/null") { |line| out << line }
+      out.strip
+    rescue Sandbox::Adapter::Box::Failed, *Envd::CONNECTION_ERRORS
+      nil
+    end
+
+    def machine(data, name)
+      Sandbox::Adapter::Machine.new(
+        id: data[:sandboxID],
+        name:,
+        state: STATES.fetch(data[:state], :running),
+        data:
+      )
+    end
+end