sandbox-adapter 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5d358100e225bf920045edf88deedbeaacb2d1f90c57d83b9b6865d70df356a
+  data.tar.gz: 7b0744d3df1da971ae6d149845544735fb55cdaeea933ac9ff41811374d5f0c6
+SHA512:
+  metadata.gz: a7839666cd9fb2a1b33c8d2ab83b9df921f196a830fa89523f9aa3338588d390ce20c9f2d8a1e08257a3313fabe24f0e95ea86a977f54f34556896e1d4b31bc1
+  data.tar.gz: 3ecb9325f46085582afe337c36bea87a375a71f5e9056b2ff8c99976bfc355fa86bade972f8eab6db0d003e3da63eeffe707dc3b625c51d72389b8fcec2448a1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nvoi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,20 @@
+# sandbox-adapter
+
+Contract for sandbox providers, and the pieces that run on any of them.
+
+- `Sandbox::Adapter::Provider`: `prepare`, `create`, `find`, `wake`, `halt`, `destroy`, `transport`, `preview`, `shapes`, `rate`, `usage`, `list`. `SandboxVm` adds `seal` and `fork`.
+- `Sandbox::Adapter::Box`: runs commands over a provider's transport. `exec` detaches the command and follows its log, resuming from the last byte after a dropped connection.
+- `Sandbox::Adapter::Checkout`: clones on the host and ships a git bundle, so the box never holds the token.
+- `Sandbox::Adapter::Steps`: users, docker, agent, checkout, setup, preview.
+
+## Configuration
+
+```ruby
+Sandbox::Adapter.providers = { "daytona" => "Sandbox::Provider::Daytona" }
+Sandbox::Adapter.credentials = MyCredentials.new # api_key(name), api_key!(name), setting(name), key(name, length:)
+Sandbox::Adapter.reporter = Rails.error
+```
+
+Credentials default to `ENV["<NAME>_API_KEY"]`, then Rails credentials.
+
+Providers live in `sandbox-provider`.

data/lib/sandbox/adapter/box.rb

@@ -0,0 +1,195 @@
+require "shellwords"
+
+# Runs commands on a box through the transport its provider handed out (see Sandbox::Adapter::Provider#transport). `run`
+# is one round trip per command, for probes. `exec` detaches the command on the box and follows its log, so a
+# dropped link costs nothing: reconnect and resume from the last byte read. `as` runs every command under
+# another account than the transport's login.
+class Sandbox::Adapter::Box
+  Failed = Class.new(StandardError)
+
+  attr_reader :transport
+
+  def initialize(transport, scratch:, as: nil, path: nil)
+    @transport = transport
+    @address = transport.address
+    @dir = scratch
+    @as = as
+    @path = path
+  end
+
+  # Retries only while the host is unreachable; any other error (bad key, refused user, host key) raises at once.
+  def wait(timeout: 300)
+    deadline = Time.current + timeout
+    begin
+      run("true")
+    rescue *@transport.connection_errors => e
+      raise Failed, "ssh to #{@address}: #{e.message}" if Time.current > deadline
+      sleep 5
+      retry
+    end
+  end
+
+  # Returns the exit status. env (symbol-keyed) is exported, dir is the working directory.
+  def run(command, env: {}, dir: nil, &)
+    @transport.exec(shell(script(command, env:, dir:)), &)
+  end
+
+  def run!(command, **, &)
+    status = run(command, **, &)
+    raise Failed, "exit #{status}: #{self.class.headline(command)}" unless status == 0
+  end
+
+  # The first line of a script that says what it does. A shell directive is not one: every script here
+  # opens with `set -e`, and a failure named after it says nothing about what failed.
+  DIRECTIVE = /\A(set|shopt|export|umask)\b/
+  def self.headline(script)
+    script.to_s.lines.map(&:strip).reject { _1.empty? || _1.match?(DIRECTIVE) }.first.to_s
+  end
+
+  # Starts `command` in its own process group under `id`, survives this connection, and streams its output from
+  # `offset` bytes on. The log is followed in bounded rounds, so a link that proxies cut when idle is never the
+  # failure signal; a dropped link is retried, and the deadline bounds only the time spent unreachable.
+  def exec(id, command, env: {}, dir: nil, offset: 0, unreachable_for: 120, &block)
+    raise ArgumentError, "bad id #{id.inspect}" unless id.to_s.match?(/\A[\w-]+\z/)
+    return attached(id, script(command, env:, dir:), &block) unless @transport.reattaches?
+
+    started = false
+    last_failure = nil
+    loop do
+      begin
+        start(id, script(command, env:, dir:)) unless started
+        started = true
+        status = follow(id, offset) { |line| offset += line.bytesize + 1; block&.call(line) }
+        return status if status
+        last_failure = nil
+      rescue *@transport.connection_errors => e
+        last_failure ||= Time.current
+        if Time.current - last_failure > unreachable_for
+          raise Failed, "#{@address} unreachable for #{unreachable_for}s: #{e.message}"
+        end
+        sleep 3
+      end
+    end
+  end
+
+  def exec!(id, command, **, &)
+    status = exec(id, command, **, &)
+    raise Failed, "exit #{status}: #{self.class.headline(command)}" unless status == 0
+  end
+
+  # The bytes of a file on the box, over SFTP on a fresh connection.
+  def download(path) = @transport.download(path)
+
+  # Writes bytes to a path on the box, creating the directory first.
+  # Files land as the transport's login, so under another account a previous copy is cleared first and the new
+  # file handed over afterwards.
+  def upload(path, io)
+    dir, file = Shellwords.escape(File.dirname(path)), Shellwords.escape(path)
+    run!(@as ? "mkdir -p #{dir} && sudo rm -f #{file}" : "mkdir -p #{dir}")
+    @transport.upload(path, io)
+    run!("sudo chown #{Shellwords.escape(@as)} #{file}") if @as
+  end
+
+  # Sends TERM to the whole process group of `id`. A command that has already recorded its status has no
+  # group left to signal, which is what cancelling a finished command means; a command with no group recorded
+  # at all is a box that could not name one, and says so rather than reporting a cancel that did nothing.
+  def cancel(id)
+    d = "#{@dir}/#{id}"
+    run!(<<~SH)
+      [ -f #{d}/exit ] && exit 0
+      [ -s #{d}/pid ] || { echo "no process group recorded for #{id}" >&2; exit 1; }
+      kill -TERM -- -"$(cat #{d}/pid)" 2>/dev/null || [ -f #{d}/exit ]
+    SH
+  end
+
+  private
+
+    # The script runs under `as` when there is one; the login stays what it is. A login shell, for the PATH
+    # a box's profile sets, unless the transport brings its own environment (this machine).
+    def shell(script)
+      flags = @transport.respond_to?(:profile?) && !@transport.profile? ? "-c" : "-lc"
+      inner = "bash #{flags} #{Shellwords.escape(script)}"
+      @as ? "runuser -u #{Shellwords.escape(@as)} -- #{inner}" : inner
+    end
+
+    # path goes first, before the environment's own exports: a login shell's PATH is the box image's, and a
+    # profile script cannot outrank what the image put in front of it. It is the layout's own string and goes
+    # in unquoted, so bash expands the ~account it starts with.
+    # Scratch sits on /tmp, which a machine's restart empties: every script makes it again before anything
+    # uses it, shared (1777) since the login and the account under `as` both write there.
+    def script(command, env:, dir:)
+      exports = env.map { |k, v| "export #{k}=#{Shellwords.escape(v.to_s)}" }
+      exports.unshift(%(export PATH=#{@path}:"$PATH")) if @path
+      scratch = "mkdir -p -m 1777 #{Shellwords.escape(@dir)} 2>/dev/null"
+      [ *exports, scratch, ("cd #{Shellwords.escape(dir)}" if dir), command ].compact.join("\n")
+    end
+
+    # One streamed request for the whole command, for a transport that cannot follow a detached one (E2B's envd,
+    # this machine's shell). The pid file holds the group the transport already put this request in, so cancel
+    # reaches the command the same way it does a detached one; proc answers on Linux and ps on a box that has
+    # it, since a slim image ships neither procps nor a reason to. Nothing calls setsid here: it forks when the
+    # caller already leads a group, and then exits 0 whatever the command did.
+    def attached(id, script, &block)
+      d = "#{@dir}/#{id}"
+      run(<<~SH, env: { NVOI_SCRIPT: script }, &block)
+        mkdir -p -m 700 #{d} && rm -f #{d}/exit
+        printf '%s\\n' "$NVOI_SCRIPT" > #{d}/script && chmod 600 #{d}/script
+        { awk '{print $5}' /proc/self/stat 2>/dev/null || ps -o pgid= -p $$ 2>/dev/null || echo $$; } \
+          | tr -d ' ' | head -1 > #{d}/pid
+        bash #{d}/script 2>&1; s=$?; echo $s > #{d}/exit; exit $s
+      SH
+    end
+
+    # The script and its log live under scratch/id. setsid makes the wrapper the group leader (its pid is the pgid);
+    # nohup keeps it alive when this session ends; the wrapper records the exit status last. Started already
+    # (a link dropped after the launch) is left alone.
+    def start(id, script)
+      d = "#{@dir}/#{id}"
+      run!(<<~SH, env: { NVOI_SCRIPT: script })
+      if [ -f #{d}/pid ] && [ ! -f #{d}/exit ] && kill -0 -- -$(cat #{d}/pid) 2>/dev/null; then exit 0; fi
+      mkdir -p -m 700 #{d} && rm -f #{d}/exit
+      printf '%s\\n' "$NVOI_SCRIPT" > #{d}/script && chmod 600 #{d}/script
+      setsid nohup bash -c 'echo $$ > #{d}/pid; bash #{d}/script > #{d}/log 2>&1; echo $? > #{d}/exit' >/dev/null 2>&1 &
+      for i in $(seq 1 50); do [ -f #{d}/pid ] && exit 0; sleep 0.1; done; exit 1
+    SH
+    end
+
+    ROUND = 45
+    # Whatever precedes it on the line, then the marker: `more` while the command runs, or an exit status.
+    MARKER = /\A(.*?)__nvoi_(more|exit) ?(\d+)?\z/
+
+    # Streams log bytes from offset for up to ROUND seconds or until the wrapper is gone. Returns the exit status
+    # once the wrapper has recorded it, nil when the round ended with the command still running.
+    def follow(id, offset, &)
+      d = "#{@dir}/#{id}"
+      status = nil
+      more = false
+      cmd = "timeout #{ROUND} tail -c +#{offset + 1} -f --pid=$(cat #{d}/pid) #{d}/log; " \
+            "if [ -f #{d}/exit ]; then " \
+            "[ -s #{d}/log ] && [ \"$(tail -c1 #{d}/log | wc -l)\" -eq 0 ] && echo; " \
+            "echo \"__nvoi_exit $(cat #{d}/exit)\"; " \
+            "elif kill -0 -- -$(cat #{d}/pid) 2>/dev/null; then echo __nvoi_more; " \
+            "else echo __nvoi_exit 255; fi"
+      # A round can end while the command is mid-line - apt prints "Generating locales..." and waits - and
+      # the marker is then written onto the end of that line. What comes before it is output; the marker is
+      # still the marker. Reading it only at the start of a line loses the round's status altogether.
+      run(cmd) do |line|
+        out, marker, code = line.match(MARKER)&.captures
+        yield out if out.present? && status.nil? && !more
+        if marker == "more" then more = true
+        elsif marker then status = code.to_i
+        elsif status.nil? && !more then yield line
+        end
+      end
+      raise Failed, "exec #{id}: no exit status" if status.nil? && !more
+      status
+    end
+
+    # Bytes arrive in arbitrary chunks; lines leave as valid UTF-8.
+    def self.each_line(buffer, data)
+      buffer << data.b
+      while (i = buffer.index("\n"))
+        yield buffer.slice!(0..i).chomp.force_encoding("UTF-8").scrub
+      end
+    end
+end

data/lib/sandbox/adapter/checkout.rb

@@ -0,0 +1,54 @@
+require "tmpdir"
+require "open3"
+
+# The repository as a git bundle made here, with the GitHub token, and unpacked on the box without it: the
+# base branch and, when origin has it, the worktree's own branch.
+class Sandbox::Adapter::Checkout
+  Bundle = Data.define(:path, :refs)
+
+  def initialize(repo, token:, url: repo.github_url)
+    @repo = repo
+    @token = token
+    @url = url
+  end
+
+  # Yields a Bundle holding `base` and any of `branches` origin knows. The file lives for the block.
+  def bundle(base, *branches)
+    Dir.mktmpdir do |dir|
+      clone = File.join(dir, "clone")
+      git(
+        dir, "clone", "-q", "--bare", "--no-tags", "--single-branch", "--branch", base, @url, clone
+      )
+      refs = [ base ]
+      branches.uniq.each do |branch|
+        next if branch == base
+        _, ok = Open3.capture2e(
+          auth_env, "git", "-C", clone, "fetch", "-q", "origin", "+#{branch}:refs/heads/#{branch}"
+        )
+        refs << branch if ok.success?
+      end
+      out = File.join(dir, "checkout.bundle")
+      git(clone, "bundle", "create", "-q", out, *refs)
+      yield Bundle.new(path: out, refs:)
+    end
+  end
+
+  private
+
+    def auth_env
+      basic = Base64.strict_encode64("x-access-token:#{@token}")
+      {
+        "GIT_CONFIG_COUNT" => "1",
+        "GIT_CONFIG_KEY_0" => "http.extraheader",
+        "GIT_CONFIG_VALUE_0" => "Authorization: Basic #{basic}"
+      }
+    end
+
+    def git(dir, *args)
+      out, status = Open3.capture2e(auth_env, "git", "-C", dir, *args)
+      unless status.success?
+        raise Sandbox::Adapter::Box::Failed, "git #{args.first}: #{out.gsub(@token.to_s, "***").strip}"
+      end
+      out
+    end
+end

data/lib/sandbox/adapter/credentials.rb

@@ -0,0 +1,44 @@
+# Where a provider's secrets come from. A provider asks by name and never reads a store: an environment
+# variable first, so a box or a CI run can set one, then this installation's credentials.
+#
+# `api_key` is the key a provider is built with; `setting` is anything else a vendor needs to be addressed,
+# such as an organization or a team. A name is always a provider's own, prefixed with its name, because
+# both sides of the lookup are shared: `PATH` is an environment variable like any other, and the
+# credentials object answers to more than the keys in the file.
+class Sandbox::Adapter::Credentials
+  # A credential that is not there. Not a Sandbox::Adapter::Provider::Error: that one is a provider refusing us,
+  # which jobs report and carry on from, and a missing credential is this installation being wrong.
+  Missing = Class.new(StandardError)
+
+  def api_key(name) = read("#{name}_api_key")
+
+  def api_key!(name)
+    api_key(name) or
+      raise Missing, "no credential for #{name}: set #{name.to_s.upcase}_API_KEY"
+  end
+
+  # A vendor's own name for something, asked for as <provider>_<what>: daytona_org_id, boat_dev_team_id.
+  def setting(name) = read(name)
+
+  # A key derived from this installation's own secret: every process derives the same one, and nothing is
+  # stored. The derivation is fixed - changing it invalidates every key a vendor has already authorised.
+  def key(label, length: 32)
+    raise Missing, "no secret to derive #{label} from" unless application
+    application.key_generator.generate_key(label, length)
+  end
+
+  private
+
+    def read(name) = env(name) || stored(name)
+
+    def env(name) = ENV[name.to_s.upcase].presence
+
+    # Read out of the credentials as a hash, never by sending the name: `key` and `content_path` are
+    # methods on that object, and sending them would answer with this installation's decryption key.
+    def stored(name)
+      return nil unless application
+      application.credentials.config[name.to_sym].presence
+    end
+
+    def application = (Rails.application if defined?(Rails) && Rails.respond_to?(:application))
+end

data/lib/sandbox/adapter/layout.rb

@@ -0,0 +1,51 @@
+# What a box looks like once a provider brings it up: who logs in, where the volume mounts, what is installed.
+# login is who the transport lands as; user is who owns the checkout and runs the agent (created on the box
+# when the login is root). browser_user renders pages the agent points at; it owns captures and nothing else.
+# volume says whether mount is a block device to put in fstab or a plain directory on the box's own disk.
+Sandbox::Adapter::Layout = Data.define(
+  :login,
+  :user,
+  :browser_user,
+  :mount,
+  :volume,
+  :volume_size,
+  :codename,
+  :node_major,
+  :playwright_version
+) do
+  DEFAULTS = {
+    user: "deploy",
+    browser_user: "browser",
+    mount: "/mnt/data",
+    volume_size: 10,
+    codename: "noble",
+    node_major: 22,
+    playwright_version: "1.63.0"
+  }.freeze
+
+  def self.for(login:, volume:) = new(login:, volume:, **DEFAULTS)
+
+  def root? = login == "root"
+  def sudo = "sudo "
+  # Everything under mount is on the volume, so a paused box keeps it.
+  def workspace = "#{mount}/workspace"
+  def claude = "#{mount}/claude"
+  def attachments = "#{mount}/attachments"
+  def playwright = "#{mount}/playwright"
+  def captures = "#{mount}/captures"
+  # What the box records about itself, such as the setup marker.
+  def state = "#{mount}/state"
+  # Created on the volume and owned by user; captures by browser_user.
+  def owned = [ workspace, claude, attachments, playwright, state ]
+
+  def scratch = "/tmp/nvoi"
+  def env_file = "/etc/nvoi/env"
+  def mcp_bin = "/usr/local/bin/nvoi-mcp"
+  # Where mise itself lands.
+  def mise = "/usr/local/bin/mise"
+  # The mise shims of the account that runs commands, named first in every command's PATH: a box image may
+  # ship a runtime of its own under /usr/local/bin, and the version the environment asked mise for is the one
+  # to answer. Written as ~account so the box's passwd says where that home is.
+  def shims = "~#{user}/.local/share/mise/shims"
+  def node_modules = "/usr/lib/node_modules"
+end

data/lib/sandbox/adapter/pages.rb

@@ -0,0 +1,11 @@
+require "net/http"
+
+# A provider's pricing page, for the providers that publish no price API: fetched, stripped of tags and
+# folded to one line, so a provider's `prices` can read its numbers with one expression each.
+module Sandbox::Adapter::Pages
+  # Markdown is asked for: a docs site answers it, a plain page ignores it.
+  def self.fetch(url) = plain(Net::HTTP.get(URI(url), { "Accept" => "text/markdown" }))
+  def self.plain(text) = text.to_s.gsub(/<[^>]+>/, " ").gsub(/\s+/, " ")
+  # Dollars as printed into cents per hour; `per` is the seconds the printed rate covers.
+  def self.cents(dollars, per: 1) = (dollars.to_f * 100 * per).round(6)
+end

data/lib/sandbox/adapter/prices.rb

@@ -0,0 +1,21 @@
+# What a provider's keys cost, cents per hour, as published by the vendor and read on AS_OF. This is the
+# table a provider is given when the installation names no other: one that keeps its own, refreshed per
+# key, hands that in instead (see Sandbox::Adapter.price_table).
+#
+# Hetzner's keys are "<server_type>:<location>" and are held in USD cents; the provider converts at
+# Sandbox::Provider::Hetzner::EUR_USD, which was read on the same day as the rates below. Refreshing one
+# without the other is what makes a price drift.
+class Sandbox::Adapter::Prices
+  AS_OF = "2026-09-22".freeze
+
+  RATES = {
+    "boat_dev" => { "small" => 1.8, "default" => 3.6, "large" => 7.2, "xlarge" => 20.0 },
+    "daytona" => { "vcpu_hour" => 5.04, "gib_hour" => 1.62, "disk_gib_hour" => 0.0108 },
+    "e2b" => { "vcpu_hour" => 5.04, "gib_hour" => 1.62 },
+    "hetzner" => { "cx23:hel1" => 1.03, "cx23:fsn1" => 1.03, "cx23:nbg1" => 1.03 }
+  }.freeze
+
+  # A key nobody published is a mistake in the caller, not a zero.
+  def cents(provider, key) = RATES.fetch(provider).fetch(key)
+  def as_of(_provider) = AS_OF
+end

data/lib/sandbox/adapter/provider.rb

@@ -0,0 +1,135 @@
+# What every provider shares, whichever interface it implements (Sandbox::Adapter::Vm, Sandbox::Adapter::SandboxVm): a machine
+# by name, reached through a transport of the provider's own. A provider never runs a process itself: Box does,
+# over that transport.
+class Sandbox::Adapter::Provider
+  class Error < StandardError
+    attr_reader :status
+    def initialize(message, status: nil) = (super(message); @status = status)
+  end
+
+  # What a vendor's API raises when it cannot be reached at all, as opposed to answering with an error.
+  UNREACHABLE = [ SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, SocketError, IOError,
+                  Net::ProtocolError, Net::HTTPBadResponse ].freeze
+
+  # A vendor that cannot be reached is a provider error like any refusal, so every caller that handles
+  # one handles an outage too.
+  def self.reaching(vendor)
+    yield
+  rescue *UNREACHABLE => e
+    raise Error, "#{vendor} unreachable: #{e.class}: #{e.message}"
+  end
+
+  # Which interface each provider implements: vm (Sandbox::Adapter::Vm) or sandbox_vm (Sandbox::Adapter::SandboxVm).
+  TYPES = %w[vm sandbox_vm].freeze
+
+  # The providers this installation has, in the order it names them (see Sandbox::Adapter.providers). Declaring
+  # none is a caller asking before the installation has said, which is worth hearing about: every list
+  # that reads this would otherwise be quietly empty, and every name not included in it.
+  def self.names
+    declared = Sandbox::Adapter.providers
+    raise Error, "no providers declared: set Sandbox::Adapter.providers" if declared.empty?
+    declared.keys
+  end
+
+  # A provider by name. Its key is <NAME>_API_KEY in the environment or <name>_api_key in credentials; a
+  # provider that is not keyed gets none.
+  def self.build(name, **)
+    klass = implementation(name)
+    klass.new(klass.keyed? ? api_key(name) : nil, **)
+  end
+
+  # The family's name for a provider's.
+  def self.type(name) = implementation(name).type
+  # Whether the provider is reached with an API key.
+  def self.keyed? = true
+
+  # The class behind a name. Named as a string and resolved when asked: an installation may name a
+  # provider whose library it does not have, and only building one says so. Resolved without inheritance,
+  # so a name that is not there raises instead of finding a top-level class that happens to share it.
+  def self.implementation(name)
+    const = Sandbox::Adapter.providers[name.to_s] or raise Error, "unknown provider #{name.inspect}"
+    Object.const_get(const, false)
+  rescue NameError => e
+    raise Error, "provider #{name} is declared as #{const}, which is not here: #{e.message}"
+  end
+
+  # Whether the class behind a name is here at all. A declared provider whose library is not installed
+  # is not available, and is said out loud once rather than raising out of every list that reads it.
+  def self.installed?(name)
+    implementation(name)
+    true
+  rescue Error => e
+    Sandbox::Adapter.reporter.report(e, handled: true, context: { provider: name })
+    false
+  end
+
+  def self.api_key(name) = Sandbox::Adapter.credentials.api_key!(name)
+
+  # Whether this installation holds that provider's credential. Asked, not caught: the bang above raises
+  # when a caller wants the key and there is none.
+  def self.api_key?(name) = Sandbox::Adapter.credentials.api_key(name).present?
+
+  # price_table answers `cents(provider_name, key)` and `as_of(provider_name)`: what a key costs, stored
+  # by whoever keeps prices. A provider does the arithmetic, never the lookup. Not to be confused with
+  # #prices below, which is the vendor's own published prices, read over the network.
+  def initialize(token, price_table: Sandbox::Adapter.price_table)
+    @token = token
+    @price_table = price_table
+  end
+
+  attr_reader :price_table
+
+  # How this provider's boxes are laid out; the same for every box unless the provider says otherwise.
+  def layout = raise NotImplementedError
+  def layout_for(_name) = layout
+
+  # Whatever the provider needs before a first create of that size; idempotent.
+  def prepare(shape = default_shape, disk = default_disk(shape)) = nil
+  # A running machine named `name`, made or found, of that size.
+  def create(name, labels: {}, shape: default_shape, disk: default_disk(shape), **)
+    raise NotImplementedError
+  end
+  def find(name) = raise NotImplementedError
+  # Running.
+  def wake(machine) = raise NotImplementedError
+  # Stopped, disk kept. Answers whether the machine is still there to wake (a VM provider removes the server
+  # and keeps only the volume).
+  def halt(machine) = raise NotImplementedError
+  # Gone; gone already counts.
+  def destroy(machine) = raise NotImplementedError
+  # What Box talks through: an object answering exec(command) { |line| } -> status, upload(path, io),
+  # download(path) -> bytes, address and connection_errors. A pinned host key applies to SSH.
+  def transport(machine, key: nil, host_key: nil, on_host_key: nil) = raise NotImplementedError
+  # Where `port` on the machine is reachable from outside, for the preview worker to proxy to: {host, scheme,
+  # token, headers}, the headers set verbatim on every request. nil is nothing to proxy to yet.
+  def preview(machine, port) = raise NotImplementedError
+
+  # Shapes this provider can serve, keyed "<cpu>x<memory>": cpu in vCPU, memory and disk in GB, rate and
+  # held in cents per hour. disk is a number where the provider ties it to the size, or {min:, max:, step:,
+  # default:} where it floats. type is the provider's own name for the size, nil when free-form. source is
+  # :api, :table or :formula; as_of is the price's date when it is not live.
+  def shapes = raise NotImplementedError
+  # Cents per hour for the shape at the chosen disk; what the ledger snapshots at open.
+  def rate(key, disk: nil) = shapes.fetch(key)[:rate]
+  # The stopped price, cents per hour.
+  def held(key, disk: nil) = shapes.fetch(key)[:held]
+  def default_shape = "2x4"
+  def default_disk(key)
+    disk = shapes.fetch(key)[:disk]
+    disk.is_a?(Hash) ? disk[:default] : disk
+  end
+  # The provider's own meter for the machine since it was made, {seconds:, cents:} running time and its
+  # price; nil when the provider keeps none. cents is nil when it meters time without a price.
+  def usage(_machine) = nil
+  # Every machine of ours at the provider; empty when it cannot be listed.
+  def list = []
+  # The provider's current prices, fetched: {source:, rates: {key => cents per hour}}. rates is nil when
+  # the source no longer parses; the whole answer is nil when the provider publishes none.
+  def prices = nil
+
+  # Providers this installation can reach: the ones whose library is here and that say so themselves. A
+  # keyed one is reachable when its credential is.
+  def self.available = names.select { installed?(_1) && implementation(_1).available?(_1) }
+
+  def self.available?(name) = api_key?(name)
+end

data/lib/sandbox/adapter/sandbox_vm.rb

@@ -0,0 +1,16 @@
+# The sandbox interface: machines from a prepared image (a snapshot, a template), named by us, copied disk and
+# memory from a running parent. Build makes the environment's seed, Fork makes worktree boxes from it. The
+# login is root; every command runs as the deploy user through Sandbox::Adapter::Box.
+class Sandbox::Adapter::SandboxVm < Sandbox::Adapter::Provider
+  def self.type = "sandbox_vm"
+  def layout = Sandbox::Adapter::Layout.for(login: "root", volume: false)
+
+  # The image machines of that size are created from, made once; idempotent.
+  def prepare(shape = default_shape, disk = default_disk(shape)) = raise NotImplementedError
+  # A seed that is done being built, as forks will read it: the same running machine where forking copies a
+  # live parent, an image of it where the provider forks from a saved state instead.
+  def seal(machine) = machine
+  # A running copy of `machine`, a sealed seed, named `name`, at the seed's size. A name already taken is
+  # the copy from a previous attempt.
+  def fork(machine, name, labels: {}, shape: nil, disk: nil) = raise NotImplementedError
+end