sandbox-adapter 0.1.1

data/lib/sandbox/adapter/ssh.rb

@@ -0,0 +1,112 @@
+require "net/ssh"
+require "net/sftp"
+
+# Reaches a box over SSH: one connection per command, SFTP for files. A nil key means the user name alone is
+# the credential (a sandbox token). host_key pins the server: nil accepts the first key seen and reports it
+# through on_host_key; a later mismatch raises. What Hetzner and Daytona hand Sandbox::Adapter::Box.
+class Sandbox::Adapter::Ssh
+  HostKeyMismatch = Class.new(Sandbox::Adapter::Box::Failed)
+  CONNECTION_ERRORS = [
+    Errno::ECONNREFUSED,
+    Errno::ECONNRESET,
+    Errno::EHOSTUNREACH,
+    Errno::ETIMEDOUT,
+    Errno::EPIPE,
+    Net::SSH::ConnectionTimeout,
+    Net::SSH::Disconnect,
+    SocketError,
+    IOError
+  ].freeze
+
+  attr_reader :host, :port, :user, :key
+
+  def initialize(host:, user:, key:, port: 22, host_key: nil, on_host_key: nil)
+    raise Sandbox::Adapter::Box::Failed, "no address" if host.blank?
+
+    @host = host
+    @port = port
+    @user = user
+    @key = key
+    @host_key = host_key
+    @on_host_key = on_host_key
+  end
+
+  def address = host
+  def connection_errors = CONNECTION_ERRORS
+  # A detached command's log can be followed again after a dropped link.
+  def reattaches? = true
+
+  # Runs a shell command line; each output line is yielded; returns the exit status.
+  def exec(command, &)
+    session { |link| return channel(link, command, &) }
+  end
+
+  def upload(path, io) = session { |link| link.sftp.upload!(io, path) }
+  def download(path) = session { |link| return link.sftp.download!(path) }
+
+  # net-ssh options for the credential: our key, or the user name alone.
+  def auth
+    key ? { key_data: [ key ], keys: [], keys_only: true } : { auth_methods: [ "none" ], keys: [] }
+  end
+
+  private
+
+    def session(&)
+      Net::SSH.start(
+        host,
+        user,
+        port:,
+        **auth,
+        non_interactive: true,
+        verify_host_key: HostKeyVerifier.new(self),
+        timeout: 10,
+        keepalive: true,
+        keepalive_interval: 15,
+        &
+      )
+    end
+
+    # net-ssh hands the presented key here. Pinned key: exact match or raise. No pin: accept and report.
+    def verify_host_key(arguments)
+      key = arguments[:key]
+      presented = "#{key.ssh_type} #{Base64.strict_encode64(key.to_blob)}"
+      if @host_key
+        unless presented == @host_key
+          raise HostKeyMismatch,
+            "#{address} presented #{key.ssh_type} #{arguments[:fingerprint]}, pinned key differs"
+        end
+      else
+        @host_key = presented
+        @on_host_key&.call(presented)
+      end
+      true
+    end
+
+    HostKeyVerifier = Struct.new(:transport) do
+      def verify(arguments) = transport.send(:verify_host_key, arguments)
+      def verify_signature(&) = yield
+    end
+
+    def channel(link, command)
+      status = nil
+      buffers = Hash.new { |h, k| h[k] = "".b }
+      link.open_channel do |ch|
+        ch.exec(command) do |c, _ok|
+          c.on_data do |_, data|
+            Sandbox::Adapter::Box.each_line(buffers[:out], data) { |line| yield line if block_given? }
+          end
+          c.on_extended_data do |_, _, data|
+            Sandbox::Adapter::Box.each_line(buffers[:err], data) { |line| yield line if block_given? }
+          end
+          c.on_request("exit-status") { |_, data| status = data.read_long }
+          c.on_close do
+            buffers.each_value do |rest|
+              yield rest.force_encoding("UTF-8").scrub if rest.present? && block_given?
+            end
+          end
+        end
+      end
+      link.loop
+      status
+    end
+end

data/lib/sandbox/adapter/steps.rb

@@ -0,0 +1,447 @@
+require "digest"
+require "shellwords"
+
+# The shell that makes a box ready, shared by every mode: a VM per worktree, a seed, a fork. Each step runs
+# detached on the box under its own id and logs every line under the loggable; a non-zero exit raises.
+class Sandbox::Adapter::Steps
+  attr_reader :layout
+
+  # mcp_script is the stub the agent talks to Rails through, handed in: a box is made the same way
+  # whichever agent runs on it, and this does not know which one wrote the script it installs. Named for
+  # the script, not the step: #mcp below is the step that installs it.
+  def initialize(
+    loggable,
+    layout:,
+    github_token:,
+    mcp_script:,
+    checkout: ->(repo) { Sandbox::Adapter::Checkout.new(repo, token: github_token) }
+  )
+    @loggable = loggable
+    @layout = layout
+    @github_token = github_token
+    # A stub that is not there writes an empty executable and the agent reaches nothing.
+    @mcp_script = mcp_script.presence or raise ArgumentError, "mcp_script is empty"
+    @checkout = checkout
+    @n = 0
+  end
+
+  attr_reader :mcp_script
+
+  # A package that asks a question stops the box. Two answers, because neither covers the other: the files
+  # written at the end of #users, which sudo cannot strip, and `env` in front of the apt calls that run
+  # before those files exist. Never a bare assignment after `$sudo`: a shell recognises an assignment
+  # before it expands, so with an empty $sudo it tries to run `DEBIAN_FRONTEND=noninteractive` instead.
+  #
+  # What a bare image lacks: sudo, curl, git, its own hostname; and the user everything else runs as. No-op where
+  # cloud-init did it. This is the first step to reach apt, so it is the one that waits for cloud-init: a fresh
+  # VM is still running its own installs, and two dpkg runs at once leave packages half configured.
+  #
+  # The C toolchain is the box's too: a gem, a wheel or a node module with a native extension is compiled here,
+  # whatever the runtime, so cc, make, pkg-config and the headers they link against come with the box. A library
+  # a single project needs, libpq for one, is that environment's setup command to install.
+  def users(box)
+    sh(box, <<~SH)
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      if [ "$(id -u)" = 0 ]; then sudo=; else sudo=sudo; fi
+      command -v cloud-init >/dev/null && { $sudo cloud-init status --wait >/dev/null || [ $? -eq 2 ]; }
+      grep -q " $(hostname)$" /etc/hosts || echo "127.0.1.1 $(hostname)" | $sudo tee -a /etc/hosts >/dev/null
+      [ -s /etc/apt/keyrings/docker.asc ] || $sudo rm -f /etc/apt/sources.list.d/docker.list /etc/apt/keyrings/docker.asc
+      for c in sudo curl git gpg cc make pkg-config; do command -v $c >/dev/null || missing=1; done
+      if [ -n "$missing" ]; then
+        $sudo apt-get update -qq
+        $sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq sudo curl ca-certificates gnupg git build-essential pkg-config libssl-dev libyaml-dev zlib1g-dev
+      fi
+      id -u #{layout.user} >/dev/null 2>&1 || $sudo useradd -m -s /bin/bash -G sudo #{layout.user}
+      [ -f /etc/sudoers.d/#{layout.user} ] || echo '#{layout.user} ALL=(ALL) NOPASSWD:ALL' | $sudo tee /etc/sudoers.d/#{layout.user} >/dev/null
+      printf 'debconf debconf/frontend select Noninteractive\n' | $sudo debconf-set-selections
+      $sudo mkdir -p /etc/needrestart/conf.d
+      printf "\\$nrconf{restart} = 'a';\\n\\$nrconf{kernelhints} = 0;\\n" | $sudo tee /etc/needrestart/conf.d/nvoi.conf >/dev/null
+      $sudo mkdir -p #{layout.scratch}
+      $sudo chmod 1777 #{layout.scratch}
+    SH
+  end
+
+  # Docker installed and its daemon up: through systemd where a box has one, else started by hand.
+  def docker(box)
+    sh(box, <<~SH)
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      if ! command -v docker >/dev/null; then
+        sudo rm -f /usr/sbin/policy-rc.d
+        sudo install -m 0755 -d /etc/apt/keyrings
+        curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /tmp/docker.asc && sudo install -m 0644 /tmp/docker.asc /etc/apt/keyrings/docker.asc
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu #{layout.codename} stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
+        sudo apt-get update -qq
+        sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-compose-plugin
+      fi
+      sudo usermod -aG docker #{layout.user}
+      if [ -d /run/systemd/system ]; then
+        sudo systemctl enable -q --now docker
+      else
+        sudo docker info >/dev/null 2>&1 || sudo sh -c 'setsid nohup dockerd >/var/log/dockerd.log 2>&1 &'
+      fi
+      for i in $(seq 1 60); do sudo docker info >/dev/null 2>&1 && exit 0; sleep 2; done
+      tail -20 /var/log/dockerd.log 2>/dev/null; exit 1
+    SH
+  end
+
+  # The MCP stub alone, for a box that has the tools already (this machine).
+  def mcp(box)
+    sh(box, <<~SH, env: { NVOI_MCP: mcp_script })
+      set -e
+      mkdir -p #{File.dirname(layout.mcp_bin)} #{layout.owned.join(" ")}
+      printf '%s' "$NVOI_MCP" > #{layout.mcp_bin} && chmod 755 #{layout.mcp_bin}
+    SH
+  end
+
+  # claude, the MCP stub through which the agent asks Rails for GitHub actions, a browser for captures, and
+  # mise. No token lands here.
+  #
+  # mise is the box's, not a repository's: every language is installed the same way, and a setup command
+  # that says `mise use -g ruby@3.4.1` finds it. The profile line is for a person who logs in; a command this
+  # app runs gets the shims from Box, which names them ahead of whatever PATH the box image came with.
+  def agent(box)
+    sh(box, <<~SH, env: { NVOI_MCP: mcp_script })
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      command -v node >/dev/null || (curl -fsSL https://deb.nodesource.com/setup_#{layout.node_major}.x | sudo -E bash - >/dev/null && sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq nodejs)
+      command -v claude >/dev/null || sudo npm install -g --silent @anthropic-ai/claude-code
+      [ -d #{layout.node_modules}/playwright-core ] || sudo npm install -g --silent playwright-core@#{layout.playwright_version}
+      printf '%s' "$NVOI_MCP" | sudo tee #{layout.mcp_bin} >/dev/null && sudo chmod 755 #{layout.mcp_bin}
+      command -v mise >/dev/null || (curl -fsSL https://mise.run | MISE_INSTALL_PATH=#{layout.mise} sudo -E sh >/dev/null)
+      printf '%s\n' 'export PATH="$HOME/.local/share/mise/shims:$PATH"' | sudo tee /etc/profile.d/mise.sh >/dev/null
+      sudo -u #{layout.user} git config --global user.name nvoi && sudo -u #{layout.user} git config --global user.email nvoi@local
+    SH
+  end
+
+  # The data directories, on the volume when there is one, else on the box's own disk. Captures belong to the
+  # browser user, who owns nothing else.
+  def storage(box, device: nil)
+    owned = layout.owned.join(" ")
+    mount =
+      if device
+        fstab = "#{device} #{layout.mount} ext4 discard,nofail,defaults 0 0"
+        "grep -q ' #{layout.mount} ' /etc/fstab || " \
+        "echo '#{fstab}' | sudo tee -a /etc/fstab >/dev/null\n      sudo mount -a"
+      else
+        "true"
+      end
+    sh(box, <<~SH)
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      sudo mkdir -p #{layout.mount}
+      #{mount}
+      sudo mkdir -p #{owned} && sudo chown #{layout.user}:#{layout.user} #{owned}
+      id -u #{layout.browser_user} >/dev/null 2>&1 || sudo useradd --system --home-dir #{layout.captures} --shell /usr/sbin/nologin #{layout.browser_user}
+      sudo mkdir -p #{layout.captures} && sudo chown #{layout.browser_user}:#{layout.browser_user} #{layout.captures}
+    SH
+  end
+
+  def browser(box)
+    sh(box, <<~SH, env: { PLAYWRIGHT_BROWSERS_PATH: layout.playwright })
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      ls #{layout.playwright} 2>/dev/null | grep -q chromium || (sudo -E env PLAYWRIGHT_BROWSERS_PATH=#{layout.playwright} npx --yes playwright-core@#{layout.playwright_version} install --with-deps chromium && sudo apt-get install -y -qq fonts-noto-cjk && sudo chown -R #{layout.user}:#{layout.user} #{layout.playwright})
+    SH
+  end
+
+  # Where the shell server is installed on a box.
+  TERMINAL_BIN = "/usr/local/bin/nvoi-terminal".freeze
+
+  # The shell server behind the Terminal view: the binary for the box's architecture (`binaries` maps
+  # `uname -m` to a local file), uploaded only when the box's differs; the machine's key written where the
+  # server reads it on every request, so a fork is given its own without a restart; and the server up as the
+  # user, starting shells in the checkout. A unit where the box has systemd, so a wake brings it back; else
+  # started detached, its pid kept. Plain round trips, not a detached step: it is short and a retry is safe.
+  def terminal(box, binaries:, key:, port:, key_file:)
+    arch = +""
+    box.run!("uname -m") { arch << _1 }
+    arch = arch.strip
+    binary = binaries[arch] or raise ArgumentError, "no terminal server for #{arch.inspect}"
+    raise ArgumentError, "#{binary} is not built: run bin/terminal" unless File.file?(binary)
+    installed = +""
+    box.run("sha256sum #{TERMINAL_BIN} 2>/dev/null") { installed << _1 }
+    upload = "#{layout.scratch}/nvoi-terminal"
+    unless installed.start_with?(Digest::SHA256.file(binary).hexdigest)
+      File.open(binary, "rb") { box.upload(upload, _1) }
+    end
+    box.run!(terminal_script(upload, port:, key_file:),
+             env: { NVOI_TERMINAL_KEY: key, NVOI_TERMINAL_UNIT: terminal_unit(port:, key_file:) })
+  end
+
+  # The checkout, from a bundle made here so no credential reaches the box. `branch` is checked out from origin
+  # when origin has it, else cut from `base`. A kept local branch is fast-forwarded, never overwritten;
+  # `fresh: true` (a seed, a fork) resets to what origin has.
+  def checkout(box, repo:, base:, branch:, fresh: false)
+    workspace = layout.workspace
+    bundle_path = "#{layout.scratch}/checkout.bundle"
+    @checkout.call(repo).bundle(base, branch) do |bundle|
+      File.open(bundle.path, "rb") { |io| box.upload(bundle_path, io) }
+      fetches = bundle.refs.map do |ref|
+        r = Shellwords.escape(ref)
+        "git fetch -q #{bundle_path} +#{r}:refs/remotes/origin/#{r}"
+      end
+      b = Shellwords.escape(branch)
+      origin_has_branch = bundle.refs.include?(branch)
+      place =
+        if fresh
+          "git checkout -qB #{b} origin/#{origin_has_branch ? b : Shellwords.escape(base)}"
+        else
+          <<~SH.strip
+            if git show-ref -q --verify refs/heads/#{b}; then
+              git checkout -q #{b}#{" && git merge -q --ff-only origin/#{b}" if origin_has_branch}
+            else
+              git checkout -qb #{b} origin/#{origin_has_branch ? b : Shellwords.escape(base)}
+            fi
+          SH
+        end
+      sh(box, <<~SH)
+        set -e
+        [ -d #{workspace}/.git ] || (git init -q #{workspace} && git -C #{workspace} remote add origin #{repo.github_url})
+        cd #{workspace}
+        #{fetches.join("\n")}
+        #{place}
+        rm -f #{bundle_path}
+        git rev-parse --abbrev-ref HEAD && git rev-parse HEAD
+      SH
+    end
+  end
+
+  # The recipe's ignores into the checkout's exclude file, its setup commands, then a marker naming what they
+  # were run for: on a fork, the same marker means the seed already did it. Every command runs, a failed one
+  # included, each reported on its own; the marker is written only when all of them passed.
+  def setup(box, environment, phases: nil)
+    recipe = environment.recipe(box, layout)
+    exclude(box, recipe.ignore) if recipe.ignore.any?
+    failed = recipe.setup_commands.filter_map do |c|
+      run = -> { sh(box, c.command, env: recipe.env, dir: layout.workspace) }
+      phases ? phases.phase(:setup, name: c.name, &run) : run.call
+      nil
+    rescue StandardError => e
+      "#{c.name}: #{e.message}"
+    end
+    raise Sandbox::Adapter::Box::Failed, "setup failed: #{failed.join("; ")}" if failed.any?
+
+    digest = Shellwords.escape(recipe.setup_digest)
+    marker = "echo #{digest} $(git rev-parse HEAD) > #{layout.state}/setup.done"
+    sh(box, marker, dir: layout.workspace)
+  end
+
+  # Whether the marker matches this environment at the checkout's HEAD.
+  def setup_done?(box, environment)
+    recipe = environment.recipe(box, layout)
+    marker = +""
+    command = "cat #{layout.state}/setup.done 2>/dev/null; echo; git rev-parse HEAD"
+    box.run(command, dir: layout.workspace) { |line| marker << line << "\n" }
+    done, _, head = marker.split("\n")
+    done.to_s.strip == "#{recipe.setup_digest} #{head.to_s.strip}"
+  end
+
+  # The app, (re)started on every call: one launcher per preview command, all of them up at once, then the
+  # port answering. A systemd unit each where a box has an init, with Caddy in front on the preview port;
+  # else a launcher detached in its own process group, its pid kept so the next call can replace it. Units
+  # of commands that are gone are removed first.
+  def preview(box, environment)
+    recipe = environment.recipe(box, layout)
+    commands = recipe.preview_commands.to_a
+    if commands.empty?
+      raise ArgumentError, "environment #{recipe.name} has no preview commands"
+    end
+
+    port = recipe.preview_port
+    env = { NVOI_ENV: env_file(recipe), NVOI_CADDY: caddyfile(port) }
+    write = []
+    start = []
+    stop = []
+    commands.each_with_index do |command, i|
+      slug = slug_of(command)
+      launcher = "#{layout.state}/preview-#{slug}"
+      unit = "nvoi-preview-#{slug}"
+      env[:"NVOI_LAUNCH_#{i}"] = launch_script(command)
+      env[:"NVOI_UNIT_#{i}"] = unit_file(launcher)
+      write << "printf '%s' \"$NVOI_LAUNCH_#{i}\" | #{layout.sudo}tee #{launcher} >/dev/null && " \
+               "#{layout.sudo}chmod 755 #{launcher}"
+      start << "printf '%s' \"$NVOI_UNIT_#{i}\" | " \
+               "sudo tee /etc/systemd/system/#{unit}.service >/dev/null"
+      stop << detached(launcher)
+    end
+    # Every unit and launcher of ours that no command claims any more, including the single one this
+    # replaced.
+    kept = commands.map { "preview-#{slug_of(_1)}" }.join(" ")
+    sh(box, <<~SH, env:)
+      set -e
+      export DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a
+      #{layout.sudo}mkdir -p #{File.dirname(layout.env_file)} #{layout.state}
+      printf '%s\\n' "$NVOI_ENV" | #{layout.sudo}tee #{layout.env_file} >/dev/null && #{layout.sudo}chmod 640 #{layout.env_file} && sudo chgrp #{layout.user} #{layout.env_file}
+      #{write.join("\n")}
+      for f in #{layout.state}/preview #{layout.state}/preview-*; do
+        case " #{kept} " in *" $(basename "$f") "*) ;; *) #{layout.sudo}rm -f "$f" "$f".pid "$f".log ;; esac
+      done
+      if [ -d /run/systemd/system ]; then
+        for u in /etc/systemd/system/nvoi-preview*.service; do
+          [ -e "$u" ] || continue
+          name="$(basename "$u" .service)"
+          case " #{commands.map { "nvoi-preview-#{slug_of(_1)}" }.join(" ")} " in
+            *" $name "*) ;;
+            *) sudo systemctl disable -q --now "$name"; sudo rm -f "$u" ;;
+          esac
+        done
+        if sudo systemctl list-units --failed --plain --no-legend 'nvoi-preview*' | grep -q .; then
+          sudo systemctl reset-failed 'nvoi-preview*'
+        fi
+        #{start.join("\n        ")}
+        sudo systemctl daemon-reload
+        for u in #{commands.map { "nvoi-preview-#{slug_of(_1)}" }.join(" ")}; do
+          sudo systemctl enable -q "$u" && sudo systemctl restart "$u"
+        done
+        command -v caddy >/dev/null || (sudo apt-get update -qq && sudo env DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt-get install -y -qq caddy)
+        printf '%s' "$NVOI_CADDY" | sudo tee /etc/caddy/Caddyfile >/dev/null
+        sudo systemctl enable -q caddy && sudo systemctl reload-or-restart caddy
+      else
+        #{stop.join("\n        ")}
+      fi
+      # A port that does not answer yet is what the loop is for; one that never does falls through to the logs.
+      for i in $(seq 1 120); do
+        if (echo > /dev/tcp/127.0.0.1/#{port}) 2>/dev/null; then exit 0; fi
+        sleep 5
+      done
+      if [ -d /run/systemd/system ]; then
+        for u in #{commands.map { "nvoi-preview-#{slug_of(_1)}" }.join(" ")}; do sudo journalctl -u "$u" -n 25 --no-pager; done
+      else
+        tail -n 25 #{layout.state}/preview-*.log
+      fi
+      exit 1
+    SH
+  end
+
+  private
+
+    # Patterns git leaves out of status and commits, each added once.
+    def exclude(box, patterns)
+      lines = patterns.map do |p|
+        q = Shellwords.escape(p)
+        file = ".git/info/exclude"
+        "grep -qxF -- #{q} #{file} 2>/dev/null || printf '%s\\n' #{q} >> #{file}"
+      end
+      sh(box, [ "set -e", "mkdir -p .git/info", *lines ].join("\n"), dir: layout.workspace)
+    end
+
+    # Every step runs detached on the box under its own id, so a dropped link resumes instead of failing the run.
+    def sh(box, command, env: {}, dir: nil)
+      @n += 1
+      id = "#{@loggable.class.name.downcase}-#{@loggable.id}-#{@n}"
+      @loggable.log(command.strip, nil)
+      box.exec!(id, command, env:, unreachable_for: 600, dir:) do |line|
+        @loggable.log(command, line)
+      end
+    end
+
+    def slug_of(command) = command.name.parameterize.presence || command.id
+
+    def terminal_command(port:, key_file:)
+      "#{TERMINAL_BIN} -addr :#{port} -key #{key_file} -dir #{layout.workspace}"
+    end
+
+    # A new binary restarts the server; otherwise one already up is left with its shells. It ends by falling
+    # through, never `exit`: Box#run is a login shell, and on boat.dev an explicit exit runs .bash_logout,
+    # whose clear_console fails and turns a success into exit 1.
+    def terminal_script(upload, port:, key_file:)
+      pid = "#{layout.state}/terminal.pid"
+      detached = "cd; setsid nohup #{terminal_command(port:, key_file:)} " \
+                 "> #{layout.state}/terminal.log 2>&1 & echo $! > #{pid}"
+      <<~SH
+        set -e
+        sudo mkdir -p #{File.dirname(key_file)} #{layout.state}
+        printf '%s' "$NVOI_TERMINAL_KEY" | sudo tee #{key_file} >/dev/null
+        sudo chown #{layout.user} #{key_file} && sudo chmod 600 #{key_file}
+        sudo chown #{layout.user} #{layout.state}
+        fresh=
+        if [ -f #{upload} ]; then
+          sudo install -m 755 #{upload} #{TERMINAL_BIN} && rm -f #{upload}
+          fresh=1
+        fi
+        if [ -d /run/systemd/system ]; then
+          printf '%s' "$NVOI_TERMINAL_UNIT" | sudo tee /etc/systemd/system/nvoi-terminal.service >/dev/null
+          sudo systemctl daemon-reload
+          sudo systemctl enable -q nvoi-terminal
+          if [ -n "$fresh" ]; then sudo systemctl restart nvoi-terminal; else sudo systemctl start nvoi-terminal; fi
+        elif [ -n "$fresh" ] || ! { [ -s #{pid} ] && sudo kill -0 "$(cat #{pid})" 2>/dev/null; }; then
+          if [ -s #{pid} ]; then sudo kill "$(cat #{pid})" 2>/dev/null || true; fi
+          sudo -u #{layout.user} -H sh -c #{Shellwords.escape(detached)}
+        fi
+        up=
+        for i in $(seq 1 50); do
+          if curl -fs -o /dev/null http://127.0.0.1:#{port}/health; then up=1; break; fi
+          sleep 0.2
+        done
+        [ -n "$up" ] || { echo "the terminal server does not answer on port #{port}" >&2; false; }
+      SH
+    end
+
+    def terminal_unit(port:, key_file:)
+      <<~UNIT
+        [Unit]
+        Description=nvoi terminal
+        After=network-online.target
+        [Service]
+        User=#{layout.user}
+        ExecStart=#{terminal_command(port:, key_file:)}
+        Restart=always
+        RestartSec=1
+        [Install]
+        WantedBy=multi-user.target
+      UNIT
+    end
+
+    def caddyfile(port)
+      <<~CADDY
+        :#{Sandbox::Adapter::Vm::PREVIEW_PORT} {
+          reverse_proxy 127.0.0.1:#{port}
+        }
+      CADDY
+    end
+
+    def unit_file(launcher)
+      <<~UNIT
+        [Unit]
+        After=docker.service network-online.target
+        [Service]
+        User=#{layout.user}
+        ExecStart=#{launcher}
+        Restart=always
+        RestartSec=2
+        [Install]
+        WantedBy=multi-user.target
+      UNIT
+    end
+
+    # No exec: a command may be a pipeline or a loop, which exec cannot take. The shell stays as the
+    # parent, which systemd tracks by cgroup and a detached start kills by process group.
+    # The shims go in by hand, as they do for every other command: this script is run by systemd or by a
+    # detached start, neither of which goes through Box, and a box image may ship a runtime of its own.
+    def launch_script(command)
+      <<~LAUNCH
+        #!/bin/bash -l
+        #{"export PATH=#{layout.shims}:\"$PATH\"" if layout.shims}
+        set -a; . #{layout.env_file}; set +a
+        cd #{layout.workspace}
+        #{command.command}
+      LAUNCH
+    end
+
+    # The env every preview command starts with: the environment's variables and PORT.
+    def env_file(recipe)
+      recipe.env.merge(PORT: recipe.preview_port).map do |k, v|
+        %(#{k}="#{v.to_s.gsub(/["\\]/) { "\\#{_1}" }}")
+      end.join("\n")
+    end
+
+    # Killed if it was up, then started again in its own process group, its pid kept.
+    def detached(launcher)
+      run = "setsid nohup #{launcher} > #{launcher}.log 2>&1 & echo $! > #{launcher}.pid"
+      run = "#{layout.sudo}runuser -u #{layout.user} -- sh -c '#{run}'"
+      kill = "#{layout.sudo}kill -TERM -- -$(cat #{launcher}.pid) 2>/dev/null"
+      "[ -f #{launcher}.pid ] && #{kill}; #{run}"
+    end
+end

data/lib/sandbox/adapter/version.rb

@@ -0,0 +1,5 @@
+module Sandbox
+  module Adapter
+    VERSION = "0.1.1"
+  end
+end

data/lib/sandbox/adapter/vm.rb

@@ -0,0 +1,42 @@
+# The traditional VM interface: a server per worktree with its own volume, booted with cloud-init, reached over
+# SSH as the deploy user with our key. Deploy is the flow. No fork: a worktree is built from scratch on its volume.
+class Sandbox::Adapter::Vm < Sandbox::Adapter::Provider
+  def self.type = "vm"
+  def layout = Sandbox::Adapter::Layout.for(login: "deploy", volume: true)
+
+  # Also the workspace's network and firewall, and what cloud-init boots with. The machine's data carries the
+  # address and the volume's device path.
+  def create(
+    name,
+    labels: {},
+    shape: default_shape,
+    disk: default_disk(shape),
+    workspace:,
+    user_data:
+  )
+    raise NotImplementedError
+  end
+  # The workspace's network and firewall, once its last machine is gone.
+  def destroy_network(workspace) = raise NotImplementedError
+
+  # `key` is the worktree's private key, the one its server was made with.
+  def transport(m, key:, host_key: nil, on_host_key: nil)
+    Sandbox::Adapter::Ssh.new(
+      host: m.data[:address],
+      user: layout.user,
+      key:,
+      host_key:,
+      on_host_key:
+    )
+  end
+
+  # The port the preview leaves the box on: the box redirects it to the app's own port (see Steps#preview).
+  # A Worker fetches a hostname on a port Cloudflare allows, not an address on any port, so the route is the
+  # address's reverse name and this port; the firewall opens it to Cloudflare alone.
+  PREVIEW_PORT = 8080
+
+  def preview(m, _port)
+    host = m.data[:hostname].presence or return nil
+    { host: "#{host}:#{PREVIEW_PORT}", scheme: "http", token: nil, headers: {} }
+  end
+end

data/lib/sandbox/adapter.rb

@@ -0,0 +1,45 @@
+# Where boxes come from. Two interfaces on one base: Sandbox::Adapter::Vm (a server per worktree, Deploy) and
+# Sandbox::Adapter::SandboxVm (a seed per environment and forks of it, Build and Fork). An environment picks a provider
+# by name; the provider hands Box a transport of its own. What a customer is told about a provider, and
+# which ones this installation offers, is Tiers.
+module Sandbox::Adapter
+  # A machine as the provider sees it. state is starting, running, stopped or broken; data is the provider's
+  # own record of it, symbol-keyed.
+  Machine = Data.define(:id, :name, :state, :data) do
+    def running? = state == :running
+    def stopped? = state == :stopped
+    def broken? = state == :broken
+  end
+
+  # What this module is given by the installation it runs in. Each one has a default that needs nothing,
+  # so the library stands on its own; an installation that answers better says so.
+  #
+  # All four are set from one place and, under a framework that reloads code, from a hook that runs after
+  # every reload: this module is reloadable too, and what is written here goes with it (see
+  # config/initializers/compute.rb).
+  class << self
+    attr_writer :credentials, :reporter, :price_table, :providers
+  end
+
+  # Where a failure that was handled is reported. Rails answers it; a library that is not in an app
+  # reports nowhere rather than crashing on a missing constant.
+  def self.reporter = @reporter ||= (defined?(Rails) ? Rails.error : NOWHERE)
+
+  NOWHERE = Object.new.tap { |o| o.define_singleton_method(:report) { |*, **| nil } }.freeze
+
+  # Where every provider's secrets are read from.
+  def self.credentials = @credentials ||= Sandbox::Adapter::Credentials.new
+
+  # The providers this installation has, name to class name, in the order a person is offered them. Held
+  # as strings so a name may be declared before its library is loaded, and so an installation that does
+  # not have one simply does not name it.
+  def self.providers = @providers ||= {}
+
+  # What a provider's keys cost. The vendors' published table until an installation keeps its own.
+  def self.price_table = @price_table ||= Sandbox::Adapter::Prices.new
+
+  # One shapes entry, as Sandbox::Adapter::Provider#shapes answers them.
+  def self.shape(cpu:, memory:, disk:, rate:, held: 0.0, type: nil, source:, as_of: nil)
+    { cpu:, memory:, disk:, type:, rate: rate.to_f, held: held.to_f, source:, as_of: }
+  end
+end