gdkbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e21ef2a459e26b8fa85bc98435127d9b32c9659a529c4a6892dedd7085a0e855
+  data.tar.gz: 506f31bc04b24adb46b25e122e9ae320caab6d68c7a80e4c3b93f431ac8fda80
+SHA512:
+  metadata.gz: 2e4a771f534a6c6abfb283dde4b162aa2ea594ef2638f74b5c4eaa49c233ba6eb0a690a7e879b42cfd8c065ff70b202f91bf30df120229af8c5aa2e92fe592ca
+  data.tar.gz: 1fb3efe4175029720b3272eebab8f5b2f083de8262a66655a055267234cc473019712f9a13a8894718c9329d7e20bdf4bdbcd6450e70a6143e9d92459e29f699

data/README.md

@@ -0,0 +1,334 @@
+# gdkbox
+
+Spin up a [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit)
+"in a box" with a single command, then connect to it from **VS Code** and run
+**Claude Code** agents against a real GitLab development environment.
+
+`gdkbox` runs GitLab's official GDK image in a Docker container, enables SSH so
+VS Code Remote-SSH can attach, and installs Claude Code inside the box for you.
+
+```
+gdkbox up myenv         # pull GDK image, start container, wire SSH + Claude Code
+gdkbox code myenv       # open the box in VS Code (Remote-SSH)
+gdkbox ssh myenv        # drop into a shell inside the box
+gdkbox ls               # list your boxes and their status
+```
+
+## How it works
+
+```
+            gdkbox up demo
+                  │
+   ┌──────────────┼─────────────────────────────────────────────┐
+   │              ▼                                               │
+   │   1. docker pull  <official GDK image>                       │
+   │   2. docker run   -p 127.0.0.1:2222:22  -p 127.0.0.1:3000:3000
+   │   3. provision    install + start sshd, authorize gdkbox key │
+   │   4. provision    npm install -g @anthropic-ai/claude-code   │
+   │   5. register     Host gdkbox-demo  ->  ~/.gdkbox/ssh_config  │
+   └──────────────────────────────────────────────────────────────┘
+                  │
+      ┌───────────┴────────────┐
+      ▼                        ▼
+  VS Code Remote-SSH       ssh gdkbox-demo -t claude
+  (ssh-remote+gdkbox-demo)  (run agents in the box)
+```
+
+- **Infra:** a Docker container per box, ports published to `127.0.0.1`.
+- **Image:** GitLab's official GDK-in-a-box image (overridable).
+- **Editor:** VS Code Remote-SSH, via a generated `~/.gdkbox/ssh_config`
+  that is `Include`d from your `~/.ssh/config`.
+- **Agents:** Claude Code is installed inside each box.
+
+## Requirements
+
+- Ruby >= 3.0
+- [Docker](https://docs.docker.com/get-docker/) installed and running
+- `ssh` and `ssh-keygen` (standard on macOS/Linux)
+- [VS Code](https://code.visualstudio.com/) with the **Remote - SSH**
+  extension, and the `code` command on your `PATH` (optional, only for
+  `gdkbox code`)
+
+## Install
+
+From this directory:
+
+```sh
+gem build gdkbox.gemspec
+gem install ./gdkbox-0.1.0.gem
+```
+
+Or run it straight from a checkout without installing:
+
+```sh
+./bin/gdkbox up myenv
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `gdkbox up NAME` | Pull the GDK image, start a box, enable SSH, install Claude Code, register VS Code host. |
+| `gdkbox ls` | List boxes and their container status (`--json` for orchestrators). |
+| `gdkbox status NAME` | Show container state and connection details (`--json`). |
+| `gdkbox dispatch NAME` | Run a Claude Code agent task headlessly in the box (`--task`/`--task-file`). |
+| `gdkbox code NAME` | Open the box in VS Code via Remote-SSH. |
+| `gdkbox ssh NAME` | Open an interactive SSH session into the box. |
+| `gdkbox claude NAME` | Install Claude Code inside the box. |
+| `gdkbox set-key NAME` | Seed/rotate the Anthropic API key in the box for unattended dispatch. |
+| `gdkbox start NAME` | Start a stopped box (and re-enable SSH). |
+| `gdkbox stop NAME` | Stop a running box. |
+| `gdkbox rm NAME` | Remove a box: container, metadata, and SSH entry. |
+| `gdkbox install-skill [NAME]` | Install the agent skill(s) bundled in this repo into your **host** Claude Code (`--project`, `--force`). |
+| `gdkbox skills` | List agent skills available to install (bundled + `~/.claude/skills` + `./.claude/skills`). |
+| `gdkbox add-skill BOX [SKILL...]` | Install skill(s) into a **box** so dispatched agents can use them; interactive picker if no SKILL (`--force`). |
+| `gdkbox completion SHELL` | Print a bash or zsh completion script (completes subcommands, flags, live box and skill names). |
+| `gdkbox harnesses` | List the agent harnesses gdkbox can install (claude, codex, opencode, pi). |
+| `gdkbox install-agent NAME` | (Re)install the box's agent harness inside it. |
+
+### `gdkbox up` options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--image` | official GDK image | Override the container image. |
+| `--ssh-port` | next free from 2222 | Host port to publish SSH on. |
+| `--web-port` | next free from 3000 | Host port to publish the GDK web UI on. |
+| `--harness ID` | `claude` (or config.yml) | Agent harness to install: claude, codex, opencode, pi. |
+| `--no-agent` | (agent installed) | Skip installing the agent harness. |
+| `--skill NAME [NAME...]` | (none) | Seed skill(s) into the box at creation for dispatched agents. |
+
+## Typical workflow
+
+```sh
+# 1. Create a box (first run pulls a large image, so give it a few minutes)
+gdkbox up demo
+
+# 2. Edit the code with VS Code Remote-SSH
+gdkbox code demo
+
+# 3. Inside the box, start GDK and run an agent
+gdkbox ssh demo
+#   gdk start          # boot the GitLab services
+#   claude             # launch a Claude Code agent against the repo
+
+# 4. The GitLab web UI is published locally
+open http://127.0.0.1:3000
+
+# 5. Stop or remove the box when you're done
+gdkbox stop demo
+gdkbox rm demo
+```
+
+## Orchestrating a fleet of agents
+
+The end goal of `gdkbox` is to back an **orchestrator** that runs a pool of
+reusable boxes and dispatches a Claude Code agent into each to execute tasks in
+parallel. Two primitives make this possible:
+
+- **Headless agent runs:** `gdkbox dispatch NAME --task "..."` runs `claude -p`
+  non-interactively inside the box and streams the agent's output. Exit status
+  mirrors the agent's. Add `--json` for structured output and `--timeout N` to
+  bound a run.
+- **Machine-readable state:** `gdkbox ls --json` / `gdkbox status NAME --json`
+  emit JSON descriptors so an orchestrator can see which boxes exist and their
+  state.
+
+For **unattended** dispatch the agents need Anthropic credentials. Seed an API
+key into each box (kept only inside the container, in a `0600` file owned by the
+GDK user — never in host-side metadata). `gdkbox up` and `gdkbox set-key` both
+default to the `ANTHROPIC_API_KEY` environment variable:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Warm a pool of 3 boxes (in parallel; first run pulls a large image).
+# The key is seeded automatically because ANTHROPIC_API_KEY is set.
+for i in 1 2 3; do gdkbox up "pool-$i" --json & done; wait
+
+# Or seed/rotate the key on existing boxes:
+gdkbox set-key pool-1
+
+# Fan three tasks out, one per box. Agents authenticate with the seeded key.
+gdkbox dispatch pool-1 --task "Run the test suite and fix the first failure" --json &
+gdkbox dispatch pool-2 --task "Update the README install section" --json &
+gdkbox dispatch pool-3 --task "Add a changelog entry" --json &
+wait
+```
+
+`gdkbox ls --json` reports `"api_key_set": true|false` per box so an
+orchestrator can tell which boxes are ready for unattended work. Prefer the
+`ANTHROPIC_API_KEY` env var over `--anthropic-api-key`, which can leak into
+shell history.
+
+In this repo the orchestrator is meant to be **another Claude Code session**,
+guided by the bundled **`gdkbox-fleet` skill** at
+[`skills/gdkbox-fleet/SKILL.md`](skills/gdkbox-fleet/SKILL.md),
+which documents the pool model, dispatch loop, state-reset-between-tasks
+caveat, and guardrails.
+
+### Installing the skill
+
+The skills shipped with this repo live in the top-level
+[`skills/`](skills/) directory. Install them into Claude Code with:
+
+```sh
+# Install every bundled skill into ~/.claude/skills (available everywhere)
+gdkbox install-skill
+
+# Install one skill, into the current project only
+gdkbox install-skill gdkbox-fleet --project
+
+# Re-install over an existing copy
+gdkbox install-skill gdkbox-fleet --force
+```
+
+This copies each skill verbatim into `~/.claude/skills/<name>` (or
+`./.claude/skills/<name>` with `--project`). Start a new Claude Code session
+afterwards to pick it up.
+
+### Giving skills to agents in a box
+
+`install-skill` targets your **host** Claude Code. Agents dispatched into a box
+(`gdkbox dispatch`) run *inside* the container and read the box's own
+`~/.claude/skills`, so they need the skill installed there. Skills can come
+from this repo (`skills/`), your host (`~/.claude/skills`), your project
+(`./.claude/skills`), or any directory path.
+
+```sh
+# See everything gdkbox can install (bundled + host + project), with summaries
+gdkbox skills
+
+# Install skill(s) into a running box; agents dispatched there can then use them
+gdkbox add-skill pool-1 gdkbox-fleet
+gdkbox add-skill pool-1 ./path/to/my-skill --force
+
+# No skill given → list and pick interactively
+gdkbox add-skill pool-1
+
+# Or seed skills when the box is first created
+gdkbox up pool-1 --skill gdkbox-fleet --skill code-history
+```
+
+Each skill is copied to `~/.claude/skills/<name>` inside the box and owned by
+the GDK user, so a dispatched `claude` agent discovers it automatically.
+
+## Agent harnesses
+
+Each box runs one agent **harness**, chosen at `gdkbox up --harness` (default
+`claude`, or the `harness:` in config.yml). `gdkbox dispatch` then runs whatever
+harness the box was created with.
+
+| Harness | CLI | Headless dispatch | Default key env | Skills dir (in box) |
+| --- | --- | --- | --- | --- |
+| `claude` | Claude Code | `claude -p` | `ANTHROPIC_API_KEY` | `~/.claude/skills` |
+| `codex` | OpenAI Codex | `codex exec` | `OPENAI_API_KEY` | `~/.codex/skills` |
+| `opencode` | opencode (sst) | `opencode run` | `OPENAI_API_KEY` | `~/.config/opencode/skills` |
+| `pi` | pi (earendil-works) | `pi -p` | `ANTHROPIC_API_KEY` | `~/.pi/skills` |
+
+```sh
+gdkbox up reviewer --harness codex          # a Codex box
+gdkbox set-key reviewer                      # seeds $OPENAI_API_KEY
+gdkbox add-skill reviewer my-skill           # installs into ~/.codex/skills
+gdkbox dispatch reviewer --task "review the diff"
+gdkbox harnesses                             # list available harnesses
+```
+
+Skills use the same `SKILL.md` format across all four, so a skill installed by
+`add-skill`/`--skill` works regardless of harness. The key env / provider for
+`opencode` and `pi` are configurable defaults — adjust per your provider.
+
+## Shell completion
+
+`gdkbox completion <shell>` prints a completion script for `bash` or `zsh`. It
+completes subcommands and flags, and — dynamically, by calling back into
+`gdkbox` — live **box names** (for `ssh`, `dispatch`, `rm`, …) and **skill
+names** (for `add-skill`, `install-skill`, and `--skill`).
+
+```sh
+# bash — add to ~/.bashrc
+eval "$(gdkbox completion bash)"
+
+# zsh — add to ~/.zshrc (after `compinit` has run)
+eval "$(gdkbox completion zsh)"
+```
+
+Or write it to your completions directory, e.g.
+`gdkbox completion bash > $(brew --prefix)/etc/bash_completion.d/gdkbox`.
+
+## Configuration
+
+| Environment variable | Purpose |
+| --- | --- |
+| `GDKBOX_HOME` | Where gdkbox stores keys, box metadata, and the SSH config (default `~/.gdkbox`). |
+| `GDKBOX_IMAGE` | Default image used by `gdkbox up` when `--image` is not given. |
+
+### `config.yml`
+
+Defaults for `gdkbox up` can be set in `~/.gdkbox/config.yml` (or
+`$GDKBOX_HOME/config.yml`). Most usefully, list skills to transfer into every
+new box so dispatched agents always have them:
+
+```yaml
+# ~/.gdkbox/config.yml
+
+# Default image for `gdkbox up` (overridden by --image or $GDKBOX_IMAGE).
+# image: registry.gitlab.com/gitlab-org/gitlab-development-kit/gitlab-gdk-in-a-box:main
+
+# Default agent harness for `gdkbox up` (overridden by --harness).
+# harness: claude
+
+# Skills transferred into every new box. Each entry is a discovered skill
+# name (see `gdkbox skills`) or a path to a skill directory.
+skills:
+  - gdkbox-fleet
+  # - code-history
+  # - ./path/to/a/local/skill
+
+# API keys seeded into boxes for unattended `gdkbox dispatch`, per provider.
+# anthropic_api_key: sk-ant-...   # used by the claude / pi harnesses
+# openai_api_key: sk-...          # used by the codex / opencode harnesses
+```
+
+`gdkbox up` installs the skills on top of any `--skill` you pass; use
+`--no-default-skills` to skip them for one run. Precedence for the image is
+`--image` > `$GDKBOX_IMAGE` > `config.yml` > built-in default; for the API key
+it is `--api-key` > the harness's provider env var (e.g. `$ANTHROPIC_API_KEY`,
+`$OPENAI_API_KEY`) > `config.yml`.
+
+> **API keys in `config.yml` are plaintext secrets on disk.** Prefer the
+> provider env var; if you do put a key in `config.yml`, keep the file mode
+> `600` (`chmod 600 ~/.gdkbox/config.yml`).
+
+State on disk:
+
+```
+~/.gdkbox/
+├── config.yml            # optional; defaults for `gdkbox up`
+├── boxes/<name>.json     # metadata for each box
+├── keys/id_ed25519(.pub) # dedicated keypair authorized into every box
+└── ssh_config            # generated; Included from ~/.ssh/config
+```
+
+`gdkbox` never touches your personal SSH keys: it creates and uses its own
+`id_ed25519` under `~/.gdkbox/keys`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec        # or: ruby -e "require 'rspec/core'; RSpec::Core::Runner.run(['spec'])"
+```
+
+The Docker, SSH, and filesystem boundaries are isolated behind small wrapper
+classes (`Docker`, `Shell`, `Store`, `SSHConfig`, `SSHKey`, `Provisioner`,
+`VSCode`), so the orchestration logic in `Box` is fully unit-tested without
+needing a running Docker daemon.
+
+## Notes & limitations
+
+- Ports are published to `127.0.0.1` only, so boxes are reachable from your
+  machine but not the wider network.
+- Processes started via `docker exec` (like `sshd`) do not survive a container
+  restart, so `gdkbox start` re-runs the SSH provisioning step to bring it back.
+- Claude Code is installed in the box but still needs your Anthropic
+  credentials at runtime — sign in the first time you run `claude` inside it.

data/exe/gdkbox

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "gdkbox/cli"
+
+begin
+  GDKBox::CLI.start(ARGV)
+rescue GDKBox::Error => e
+  warn e.message
+  exit 1
+end

data/lib/gdkbox/box.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "time"
+
+module GDKBox
+  # A single GDK-in-a-box instance: a Docker container plus its persisted
+  # metadata. This is the orchestration layer the CLI talks to.
+  class Box
+    # Outcome of a headless agent run inside a box.
+    AgentResult = Struct.new(:stdout, :stderr, :status) do
+      def success?
+        status.zero?
+      end
+    end
+
+    attr_reader :name, :config
+
+    def initialize(name, config:, shell: Shell.new, docker: nil, store: nil, ssh_key: nil)
+      @name = name
+      @config = config
+      @shell = shell
+      @docker = docker || Docker.new(shell: shell)
+      @store = store || Store.new(config: config)
+      @ssh_key = ssh_key || SSHKey.new(config: config, shell: shell)
+    end
+
+    def self.all(config:, store: nil, **kwargs)
+      store ||= Store.new(config: config)
+      store.all.map { |data| from_data(data, config: config, store: store, **kwargs) }
+    end
+
+    def self.from_data(data, config:, **kwargs)
+      box = new(data["name"], config: config, **kwargs)
+      box.instance_variable_set(:@data, data)
+      box
+    end
+
+    def data
+      @data ||= @store.load(name)
+    end
+
+    def exists?
+      @store.exists?(name)
+    end
+
+    def container_name
+      data ? data["container_name"] : @config.container_name(name)
+    end
+
+    def ssh_port
+      data && data["ssh_port"]
+    end
+
+    def web_port
+      data && data["web_port"]
+    end
+
+    def web_url
+      "http://127.0.0.1:#{web_port}"
+    end
+
+    def ssh_host_alias
+      @config.ssh_host_alias(name)
+    end
+
+    def remote_path
+      data ? data["remote_path"] : @config.remote_path
+    end
+
+    # The agent harness this box runs (defaults to Claude for boxes created
+    # before harness support existed).
+    def harness
+      Harness[(data && data["harness"]) || Harness.default]
+    end
+
+    def state
+      @docker.state(container_name)
+    end
+
+    # Provision a brand new box end to end: pull image, run container, enable
+    # SSH, optionally install the agent harness, then persist metadata.
+    def create!(image: nil, ssh_port: nil, web_port: nil, harness: Harness.default,
+      install_agent: true, api_key: nil)
+      raise Error, "Box '#{name}' already exists" if exists?
+
+      harness = Harness[harness]
+      image ||= @config.default_image
+      public_key = @ssh_key.ensure!
+      cname = @config.container_name(name)
+
+      @docker.pull(image)
+
+      # Reserve the host ports atomically. `next_port` reads the store, so
+      # parallel `gdkbox up` runs would otherwise all pick the same "next free"
+      # port and collide at `docker run`. Holding an exclusive lock while we
+      # choose ports *and* persist a preliminary record makes each sibling see
+      # the others' reservations.
+      ssh_port, web_port = reserve_ports!(cname, ssh_port, web_port)
+
+      begin
+        @docker.run_container(
+          name: cname,
+          image: image,
+          publish: [
+            "127.0.0.1:#{ssh_port}:#{Config::SSH_CONTAINER_PORT}",
+            "127.0.0.1:#{web_port}:#{Config::GDK_WEB_CONTAINER_PORT}"
+          ],
+          labels: { "gdkbox" => "true", "gdkbox.name" => name }
+        )
+      rescue StandardError
+        # The container never started, so release the reserved ports rather
+        # than stranding a record that points at nothing.
+        @store.delete(name)
+        raise
+      end
+
+      provisioner = Provisioner.new(docker: @docker, config: @config)
+      provisioner.setup_ssh(cname, public_key)
+
+      # Enrich the reserved record now that the box is reachable over SSH,
+      # before the optional Claude/API-key steps. That way a failure in those
+      # steps leaves a box that `gdkbox ls`/`rm` can still see and clean up,
+      # rather than an orphan container with no record.
+      @data = @data.merge(
+        "image" => image,
+        "ssh_user" => @config.ssh_user,
+        "remote_path" => @config.remote_path,
+        "harness" => harness.id,
+        "created_at" => Time.now.utc.iso8601
+      )
+      @store.save(@data)
+
+      provisioner.setup_agent(cname, harness) if install_agent
+      @data["agent_installed"] = install_agent
+
+      if api_key && !api_key.strip.empty?
+        provisioner.setup_api_key(cname, api_key, harness.key_env)
+        @data["api_key_set"] = true
+      end
+
+      @store.save(@data)
+      @data
+    end
+
+    # Start a stopped box and make sure sshd is running again (processes
+    # started via `docker exec` do not survive a container restart).
+    def start!
+      @docker.start(container_name)
+      Provisioner.new(docker: @docker, config: @config)
+        .setup_ssh(container_name, @ssh_key.ensure!)
+    end
+
+    def stop!
+      @docker.stop(container_name)
+    end
+
+    def destroy!
+      @docker.rm(container_name, force: true)
+      @store.delete(name)
+    end
+
+    # (Re)install this box's agent harness inside the container.
+    def install_agent!
+      Provisioner.new(docker: @docker, config: @config).setup_agent(container_name, harness)
+      return unless data
+
+      @data = data.merge("agent_installed" => true)
+      @store.save(@data)
+    end
+
+    # Install an agent skill into this box's harness skills directory so agents
+    # dispatched into the box can use it. `token` is a discovered skill name
+    # (bundled, ~/.claude/skills, or ./.claude/skills) or a path to a skill
+    # directory. Skills use the same SKILL.md format across harnesses; only the
+    # destination directory differs. Returns the resolved Skill.
+    def install_skill(token, project_dir: Dir.pwd, force: false)
+      raise Error, "Box '#{name}' does not exist" unless exists?
+
+      skill = Skills.resolve(token, project_dir: project_dir)
+      skills_dir = "/home/#{@config.ssh_user}/#{harness.skills_subdir}"
+      target = "#{skills_dir}/#{skill.name}"
+
+      @docker.exec(container_name, 'mkdir -p "$GDKBOX_SKILLS_DIR"',
+        user: @config.ssh_user, env: { "GDKBOX_SKILLS_DIR" => skills_dir })
+
+      present = @docker.exec(
+        container_name, '[ -e "$GDKBOX_TARGET" ] && echo yes || echo no',
+        user: @config.ssh_user, env: { "GDKBOX_TARGET" => target }, check: false
+      ).stdout.strip == "yes"
+      raise Error, "Skill '#{skill.name}' is already in box '#{name}'. Use --force to overwrite." if present && !force
+
+      @docker.exec(container_name, 'rm -rf "$GDKBOX_TARGET"',
+        user: @config.ssh_user, env: { "GDKBOX_TARGET" => target }) if present
+
+      @docker.cp_into(container_name, skill.path, target)
+      @docker.exec(container_name, 'chown -R "$GDKBOX_USER:$GDKBOX_USER" "$GDKBOX_TARGET"',
+        user: "root", env: { "GDKBOX_USER" => @config.ssh_user, "GDKBOX_TARGET" => target })
+
+      skill
+    end
+
+    # Seed or rotate the agent API key inside an existing box so dispatched
+    # agents can authenticate unattended. The key is exported under the env
+    # var this box's harness reads.
+    def set_api_key!(api_key)
+      raise Error, "Box '#{name}' does not exist" unless exists?
+      raise Error, "An API key is required" if api_key.nil? || api_key.strip.empty?
+
+      Provisioner.new(docker: @docker, config: @config)
+        .setup_api_key(container_name, api_key, harness.key_env)
+      @data = data.merge("api_key_set" => true)
+      @store.save(@data)
+    end
+
+    # Run this box's agent harness non-interactively and capture its output.
+    # This is the primitive an orchestrator uses to dispatch a task to a box.
+    # The task text is passed through the environment so arbitrary prompts
+    # cannot break out of the shell command.
+    def run_agent(task:, json: false, yolo: true, timeout: nil)
+      raise Error, "Box '#{name}' does not exist" unless exists?
+
+      agent = harness.agent_command(json: json, yolo: yolo)
+      agent = "timeout #{Integer(timeout)} #{agent}" if timeout
+      # Source the seeded API key (if any) so the agent authenticates unattended.
+      command = %([ -f "$HOME/.gdkbox/env" ] && . "$HOME/.gdkbox/env"; #{agent})
+
+      result = @docker.exec(
+        container_name, command,
+        user: @config.ssh_user,
+        workdir: remote_path,
+        env: { "GDKBOX_TASK" => task },
+        check: false
+      )
+      AgentResult.new(result.stdout, result.stderr, result.status)
+    end
+
+    # A machine-readable summary for orchestrators (`gdkbox ls --json`).
+    def summary(state: nil)
+      {
+        "name" => name,
+        "state" => (state || self.state).to_s,
+        "container_name" => container_name,
+        "ssh_host" => ssh_host_alias,
+        "ssh_port" => ssh_port,
+        "web_port" => web_port,
+        "web_url" => web_url,
+        "remote_path" => remote_path,
+        "harness" => harness.id,
+        "agent_installed" => (data && data["agent_installed"]) || false,
+        # Back-compat: orchestrators predating multi-harness check this field.
+        "claude_installed" => (harness.id == "claude" && (data && data["agent_installed"])) || false,
+        "api_key_set" => (data && data["api_key_set"]) || false
+      }
+    end
+
+    # argv to open an interactive SSH session using the generated config.
+    def ssh_command
+      ["ssh", ssh_host_alias]
+    end
+
+    private
+
+    # Choose free host ports and persist a preliminary record claiming them,
+    # all while holding an exclusive lock so concurrent `create!` calls in
+    # separate processes serialize and cannot pick the same ports. Returns the
+    # chosen [ssh_port, web_port]. Caller-supplied ports are honored as-is.
+    def reserve_ports!(cname, ssh_port, web_port)
+      @config.ensure_dirs!
+      File.open(@config.lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        ssh_port ||= next_port(Config::SSH_PORT_BASE)
+        web_port ||= next_port(Config::WEB_PORT_BASE, exclude: [ssh_port])
+        @data = {
+          "name" => name,
+          "container_name" => cname,
+          "ssh_port" => ssh_port,
+          "web_port" => web_port,
+          "agent_installed" => false,
+          "api_key_set" => false
+        }
+        @store.save(@data)
+        [ssh_port, web_port]
+      end
+    end
+
+    def next_port(base, exclude: [])
+      used = @store.used_ports + exclude
+      port = base
+      port += 1 while used.include?(port)
+      port
+    end
+  end
+end