@clipboard-health/groundcrew 2.2.0 → 2.3.0

package/README.md

@@ -15,7 +15,12 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
 ## Quickstart
 
-1. **Install prereqs.** Node 24, `git`, `cmux` _or_ `tmux`, and the agent CLIs themselves (`claude`, `codex`, `cursor-agent`, ...). Groundcrew is **macOS-only** and requires [Safehouse](https://agent-safehouse.dev/) on `PATH`. Optional: `codexbar` for session-usage gating. The `workspaceKind` config key picks the workspace backend (`auto` resolves to cmux when installed, else tmux).
+1. **Install prereqs.** Node 24, `git`, `cmux` _or_ `tmux`, and the agent CLIs themselves (`claude`, `codex`, `cursor-agent`, ...). Pick a local isolation backend below depending on platform and what the agent needs to do. Optional: `codexbar` for session-usage gating. The `workspaceKind` config key picks the workspace backend (`auto` resolves to cmux when installed, else tmux).
+   - **`safehouse`** (macOS default) — [Safehouse](https://agent-safehouse.dev/) on `PATH`. The fastest local backend; cannot safely give the agent Docker.
+   - **`sdx`** (Linux default, macOS opt-in) — [Docker Sandboxes](https://docs.docker.com/sandboxes/) (`sbx`) on `PATH`. Required when a ticket needs the agent to use Docker (`docker build`, `docker run`, integration tests). Each model that should run under sdx needs a `sandbox: { agent: "<sbx-agent>" }` block in `config.ts` so groundcrew knows which sbx agent to address.
+   - **`none`** — explicit unsandboxed escape hatch. Never picked implicitly; `crew doctor` warns when it is configured.
+
+   Groundcrew resolves `local.runner` per platform: macOS → `safehouse`, Linux/WSL → `sdx`. Set `local.runner` to `"safehouse" | "sdx" | "none"` to override; leave at `"auto"` for the platform default.
 
 2. **Create a Linear project to scope your work.** Any team works — make a project inside it and drop tickets in. The orchestrator polls by project, not by team, so you don't need a dedicated team.
 
@@ -63,11 +68,11 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
    `LINEAR_API_KEY` continues to work for existing setups; if both variables are set, `GROUNDCREW_LINEAR_API_KEY` wins.
 
-5. **Prepare the runner and agent auth.** Groundcrew supports one runner: a `cmux` or `tmux` workspace on macOS, with Safehouse on `PATH`, `clearance`, and locally authenticated agent CLIs.
+5. **Prepare the runner and agent auth.** Groundcrew uses a `cmux` or `tmux` workspace hosting the resolved local backend (`safehouse`, `sdx`, or `none`) plus locally authenticated agent CLIs. Setup fails fast when the resolved backend's binary or platform requirement is missing — `safehouse` requires macOS + `safehouse` on PATH; `sdx` requires macOS or Linux + `sbx` on PATH. `models.isolation` and per-model `isolation` are legacy keys and fail config validation. Per-model `sandbox` blocks are accepted again and used by the `sdx` runner.
 
-   Setup fails before creating a worktree when the host is not macOS or `safehouse` is missing. `models.isolation`, per-model `isolation`, and per-model `sandbox` are legacy keys and now fail config validation.
+   For sdx, sandboxes are created automatically on first launch. Groundcrew names them deterministically as `groundcrew-<repository>-<model>`, probes `sbx ls`, and runs `sbx create [--template ...] [--kit ...] <agent> <projectDir>` when missing — `projectDir` is the mount so every per-ticket worktree (created as a sibling of the bare clone) is visible inside the sandbox. First-time agent auth happens inside the sandbox the first time the agent runs via `sbx exec`. To bootstrap manually instead, run `sbx create --name groundcrew-<repo>-<model> <agent> <projectDir>` once.
 
-6. **Set the clearance allowlist for local macOS runs.** Groundcrew starts `clearance` from `@clipboard-health/clearance` on `http://127.0.0.1:19999` (skipping the launch if something is already listening) and runs the agent through the bundled `safehouse-clearance` wrapper. Clearance refuses to start without an allowlist — see [its README](https://github.com/ClipboardHealth/core-utils/tree/main/packages/clearance) for the proxy's env vars, log paths, and DNS rules. The shortest path is to set the env before `crew run`:
+6. **Set the clearance allowlist for local Safehouse runs.** Only applies when `local.runner` resolves to `safehouse`. Groundcrew starts `clearance` from `@clipboard-health/clearance` on `http://127.0.0.1:19999` (skipping the launch if something is already listening) and runs the agent through the bundled `safehouse-clearance` wrapper. Clearance refuses to start without an allowlist — see [its README](https://github.com/ClipboardHealth/core-utils/tree/main/packages/clearance) for the proxy's env vars, log paths, and DNS rules. The shortest path is to set the env before `crew run`:
 
    ```bash
    CLEARANCE_ALLOW_HOSTS="api.openai.com,auth.openai.com,api.anthropic.com,mcp.linear.app,api.linear.app" \
@@ -112,12 +117,14 @@ Required fields are marked **required**; everything else has a default and can b
 | `orchestrator.sessionLimitPercentage`   | `85`                | Number in `(0, 100]`. A model whose codexbar session window exceeds this percentage is skipped that tick.                                                                                                                                                                                 |
 | `models.default`                        | `"claude"`          | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew run --ticket <TICKET>` for unlabeled tickets. `crew run` without `--ticket` ignores unlabeled tickets and does not apply this default. Must exist in `models.definitions`. |
 | `models.definitions`                    | `{ claude, codex }` | Agent definitions. Additive merge with shipped defaults.                                                                                                                                                                                                                                  |
-| `models.definitions.<name>.cmd`         | —                   | Shell command launched for the model. Runs in the worktree through Safehouse/clearance. `{{worktree}}` is replaced before launch and legacy `{{sandbox}}` expands to an empty string.                                                                                                     |
+| `models.definitions.<name>.cmd`         | —                   | Shell command launched for the model. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise.                                               |
 | `models.definitions.<name>.color`       | —                   | Color for the workspace status pill (cmux only; tmux silently drops it).                                                                                                                                                                                                                  |
 | `models.definitions.<name>.usage`       | optional            | If set, codexbar usage is fetched for this model and gated by `sessionLimitPercentage`. Omit to never gate. When `usage.codexbar.source` is omitted, groundcrew uses `auto` on macOS and `cli` elsewhere.                                                                                 |
+| `models.definitions.<name>.sandbox`     | optional            | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Fields: `agent` (required sbx agent name), `template`, `kits`, `setupCommand` (override for the inside-sandbox setup script).                                                           |
 | `models.definitions.<name>.disabled`    | optional            | When set to exactly `true`, drops the named shipped default (`claude` or `codex`). Doctor skips probing it; `agent-<name>` labels fall back to `models.default` with a warning. See "Disabling a shipped default" below.                                                                  |
 | `prompts.initial`                       | (template)          | First message sent to the agent. Placeholders: `{{ticket}}`, `{{worktree}}`, `{{title}}`, `{{description}}`.                                                                                                                                                                              |
 | `workspaceKind`                         | `"auto"`            | Terminal session manager. `"auto"` picks `cmux` when on PATH, else `tmux`. Set to `"cmux"` or `"tmux"` to fail loudly when the chosen backend is missing. tmux windows live in a dedicated `groundcrew` session.                                                                          |
+| `local.runner`                          | `"auto"`            | Local isolation backend. `"auto"` resolves to `safehouse` on macOS and `sdx` on Linux/WSL. Explicit values: `"safehouse"`, `"sdx"`, `"none"`. `"none"` is never picked implicitly — doctor warns when it is configured.                                                                   |
 | `logging.file`                          | XDG state path      | Append-mode log file destination. `log()` / `logEvent()` tee here in addition to stdout, so a vanished workspace doesn't take the evidence with it. Defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/groundcrew/groundcrew.log`.                                                        |
 
 The branch prefix (`<prefix>-<TICKET>`) is derived from your OS username (`os.userInfo().username`), not configured. Agent selection looks for a top-level Linear label named `agent-<model>` (e.g. `agent-claude`, `agent-codex`). **`crew run` without `--ticket` only fetches tickets with an `agent-*` label** — the GraphQL query filters them server-side, so unlabeled tickets are never returned by Linear's API and do not appear in the rendered board. Use `crew run --ticket <TICKET>` to provision an unlabeled ticket on demand (manual setup falls back to `models.default`). The reserved label `agent-any` routes the ticket to the configured model with the most available session capacity (lowest codexbar session-used percent), skipping any model already over `sessionLimitPercentage`. With no usage data, `agent-any` resolves to `models.default`. The name `any` cannot be used in `models.definitions`. Todo tickets blocked by Linear issues that are not in `linear.statuses.terminal` are skipped until their blockers reach a terminal status.
@@ -164,16 +171,16 @@ crew cleanup <TICKET>
 
 ## Gotchas
 
-- **Execution is macOS plus Safehouse only.** There is no `models.isolation` strategy and no direct local execution mode. Linux/WSL is not supported.
+- **Local execution picks one of safehouse/sdx/none.** `local.runner: "auto"` resolves to `safehouse` on macOS and `sdx` (Docker Sandboxes) on Linux/WSL. Override with `local.runner: "safehouse" | "sdx" | "none"`. There is no per-model `isolation` knob anymore — the runner is global. `sdx` requires a per-model `sandbox: { agent }` block so groundcrew can map the model to an sbx agent.
 - **Safehouse-already-wrapped commands are not re-wrapped.** If a `models.definitions.<name>.cmd` already starts with `safehouse`, groundcrew assumes that command owns its Safehouse flags and does not add the `safehouse-clearance` wrapper a second time. Changing the proxy's allowlist after it's running requires killing the PID in `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid` so the next launch picks up the new env.
-- **Legacy Docker Sandboxes state is unmanaged.** Groundcrew no longer discovers or cleans `.sbx` worktrees or persistent Docker Sandboxes containers. If you have old state, inspect and remove it manually with `sbx`.
+- **Sandbox lifecycle is create-only.** Groundcrew auto-creates the sandbox for a `<repository, model>` pair when missing, but never deletes one — sandboxes persist across tickets and across `crew cleanup`. Auth state lives inside the sandbox, so deleting it forces a re-login. Inspect or remove them manually with `sbx ls` / `sbx rm`.
 - **Dead tmux windows vanish by default.** When a wrapped agent command fails (e.g. `safehouse-clearance` not found, `npm install` crash), the tmux window closes immediately and the error scrolls into the void. Set `GROUNDCREW_KEEP_DEAD_WINDOWS=1` (any non-empty value works) in the env you launch `crew` from to flip the per-window `remain-on-exit` to `on`; the window stays open with the error visible. Close it manually with `tmux kill-window -t groundcrew:<ticket>` after diagnosis. tmux backend only.
 - **Status names matter.** If your team uses `Started` instead of `In Progress`, set `linear.statuses.inProgress = "Started"`.
 - **Leaf-only.** Parent issues with children are ignored — sub-issues are the work items.
 - **Tickets stay in the in-progress status until something else moves them.** Groundcrew sets a ticket to `inProgress` when it provisions a workspace and never advances it. The next transition (typically "in review" when a PR opens) is left to your team's Linear automation rules.
 - **Project must be on a single Linear team in practice.** Cross-team projects work — the orchestrator caches the in-progress state ID per team — but every team in the project must use the same status name for `linear.statuses.inProgress`.
 - **Claude launches in bypass-permissions mode by default.** Groundcrew creates isolated per-ticket worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode bypassPermissions` to avoid workspace-trust and tool-permission prompts blocking automation. Override `models.definitions.claude.cmd` if you want a stricter mode.
-- **Doctor's command introspection is shallow.** Doctor reports whether the host can run local tickets with macOS plus Safehouse, then tokenizes model `cmd` and checks the first two non-flag tokens against PATH (so `safehouse claude --foo` checks both `safehouse` and `claude`). Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed — verify those manually. In particular, `npx -y claude` and `env FOO=1 claude` only check the wrapper, not the wrapped CLI.
+- **Doctor's command introspection is shallow.** Doctor reports the resolved local runner (safehouse / sdx / none) and whether its prerequisites are met, then tokenizes model `cmd` and checks the first two non-flag tokens against PATH (so `safehouse claude --foo` checks both `safehouse` and `claude`). Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed — verify those manually. In particular, `npx -y claude` and `env FOO=1 claude` only check the wrapper, not the wrapped CLI. When `local.runner` is `"none"`, doctor surfaces a single WARNING line so the unsandboxed launch is visible at a glance.
 - **Doctor checks every enabled model, including shipped defaults you didn't disable.** `models.definitions` includes both shipped defaults (`claude`, `codex`) by default via additive merge. If you only intend to label tickets `agent-claude` and don't have `codex` installed, set `models.definitions.codex: { disabled: true }` (see "Disabling a shipped default" under "Config reference"). Without that, doctor exits non-zero on a missing `codex` binary even though `crew run` would never route to it.
 - **Switch to tmux if cmux is misbehaving.** Set `workspaceKind: "tmux"` to force the tmux backend when cmux's CLI/socket bridge is flaky (symptoms: `cmux --json list-workspaces` returning `Failed to write to socket (Broken pipe)` or `Socket not found at ...cmux.sock` on every tick). tmux is more reliable — just a unix socket, no GUI app — at the cost of losing cmux's status pills, notifications, and vertical-tab sidebar.
 - **Agent CLI must accept a positional prompt.** The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, and `cursor-agent` all support this.

package/configExample.ts

@@ -44,9 +44,18 @@ export const config: Config = {
   //       cmd: "cursor-agent",
   //       color: "#929292",
   //     },
+  //     // To run a model under the sdx (Docker Sandboxes) runner, bind it to
+  //     // an sbx agent. Required when `local.runner` resolves to `sdx`.
+  //     // claude: { sandbox: { agent: "claude" } },
   //   },
   // },
   //
+  // // Local isolation backend. Defaults to `"auto"` — macOS → safehouse,
+  // // Linux → sdx (Docker Sandboxes). `"none"` is an explicit unsandboxed
+  // // escape hatch and is never picked implicitly. Switch to `"sdx"` on
+  // // macOS when you need an agent to use Docker safely.
+  // local: { runner: "auto" },
+  //
   // prompts: {
   //   initial: [
   //     "Begin work on {{ticket}} ({{title}}) in the {{worktree}} wt subdirectory.",

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwIH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA6D/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8IH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAkE/C"}

package/dist/commands/doctor.js

@@ -3,8 +3,9 @@
  * Returns true if every required check passes; false otherwise.
  */
 import { existsSync, statSync } from "node:fs";
-import { loadConfig } from "../lib/config.js";
+import { loadConfig, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
+import { resolveLocalRunner } from "../lib/localRunner.js";
 import { errorMessage, resolveLinearApiKey, writeOutput } from "../lib/util.js";
 import { resolveWorkspaceKind } from "../lib/workspaces.js";
 // Tokenization stops after this many non-flag tokens. Two is enough to
@@ -140,8 +141,13 @@ export async function doctor() {
         writeOutput(`[--] host: ${errorMessage(error)}`);
         return false;
     }
-    const localCapability = localCapabilityCheck(host);
-    reportLocalCapability(localCapability);
+    const resolvedRunner = resolveLocalRunner(config.local.runner, host);
+    const localCapability = localCapabilityCheck(host, resolvedRunner);
+    reportLocalCapability({
+        check: localCapability,
+        setting: config.local.runner,
+        resolved: resolvedRunner,
+    });
     const workspaceOutcome = resolveWorkspaceOutcome(config, host);
     reportWorkspaceKind(config, workspaceOutcome);
     const checks = [
@@ -176,22 +182,43 @@ export async function doctor() {
     writeOutput("All required checks passed.");
     return true;
 }
-function localCapabilityCheck(host) {
-    const supportsLocalRunner = host.isSafehouseSupported && host.hasSafehouse;
+function localCapabilityCheck(host, resolved) {
+    if (resolved === "safehouse") {
+        const ok = host.isSafehouseSupported && host.hasSafehouse;
+        return {
+            name: "local runner (safehouse)",
+            ok,
+            required: false,
+            hint: ok
+                ? "ready"
+                : "safehouse runner requires macOS with `safehouse` on PATH (install from https://agent-safehouse.dev/)",
+        };
+    }
+    if (resolved === "sdx") {
+        const ok = host.isSdxSupported && host.hasSbx;
+        return {
+            name: "local runner (sdx)",
+            ok,
+            required: false,
+            hint: ok
+                ? "ready"
+                : "sdx runner requires `sbx` (Docker Sandboxes) on PATH (install from https://docs.docker.com/sandboxes/)",
+        };
+    }
+    // resolved === "none"
     return {
-        name: "local runner (macOS + Safehouse)",
-        ok: supportsLocalRunner,
+        name: "local runner (none)",
+        ok: true,
         required: false,
-        hint: supportsLocalRunner
-            ? "ready"
-            : "groundcrew requires macOS with Safehouse on PATH (install from https://agent-safehouse.dev/)",
+        hint: "WARNING: local.runner='none' — agent runs unsandboxed on the host. Only use this when you understand the implications.",
     };
 }
-function reportLocalCapability(check) {
+function reportLocalCapability(arguments_) {
     writeOutput();
     writeOutput("Local runner");
     writeOutput("------------");
-    writeOutput(format(check));
+    writeOutput(`requested: ${arguments_.setting} → resolved: ${arguments_.resolved}`);
+    writeOutput(format(arguments_.check));
 }
 function resolveWorkspaceOutcome(config, host) {
     try {

package/dist/commands/setupWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA6Ef;AA0FD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CAoGf;AA0FD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/commands/setupWorkspace.js

@@ -1,13 +1,14 @@
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { ensureClearance } from "@clipboard-health/clearance";
 import { fetchResolvedIssue } from "../lib/boardSource.js";
 import { BUILD_SECRET_NAMES, loadConfig } from "../lib/config.js";
+import { ensureSandbox, sandboxNameFor } from "../lib/dockerSandbox.js";
 import { detectHostCapabilities } from "../lib/host.js";
 import { buildLaunchCommand, shellSingleQuote } from "../lib/launchCommand.js";
 import { createLinearIssueStatusUpdater } from "../lib/linearIssueStatus.js";
-import { assertLocalRunnerRequirements } from "../lib/localRunner.js";
+import { assertLocalRunnerRequirements, resolveLocalRunner } from "../lib/localRunner.js";
 import { errorMessage, getLinearClient, log, readEnvironmentVariable } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
 import { isWorktreeAlreadyExistsError, worktrees } from "../lib/worktrees.js";
@@ -75,8 +76,16 @@ export async function setupWorkspace(config, options, runOptions = {}) {
     if (!definition) {
         throw new Error(`Unknown model: ${model}`);
     }
-    assertLocalRunnerRequirements(await detectHostCapabilities(signal));
-    await ensureClearance({ logger: log });
+    const host = await detectHostCapabilities(signal);
+    const runner = resolveLocalRunner(config.local.runner, host);
+    assertLocalRunnerRequirements(host, runner);
+    if (runner === "safehouse") {
+        await ensureClearance({ logger: log });
+    }
+    if (runner === "sdx" && definition.sandbox === undefined) {
+        throw new Error(`Local groundcrew runs with the sdx runner require a sandbox config on model '${model}'. ` +
+            "Add `sandbox: { agent: '<sbx-agent-name>' }` to the model in your config.ts.");
+    }
     const spec = { repository, ticket };
     let created;
     try {
@@ -113,11 +122,21 @@ export async function setupWorkspace(config, options, runOptions = {}) {
         const stagedPrompt = stagePrompt({ config, ticket, ticketDetails, worktreeName });
         promptDir = stagedPrompt.directory;
         const secretsFile = stageBuildSecrets(promptDir);
+        const sandboxName = runner === "sdx" ? sandboxNameFor({ repository, model }) : undefined;
+        if (runner === "sdx" && sandboxName !== undefined && definition.sandbox !== undefined) {
+            await ensureSandbox({
+                sandboxName,
+                sandbox: definition.sandbox,
+                mountPath: resolve(config.workspace.projectDir),
+            }, signal);
+        }
         const launchCommand = buildLaunchCommand({
             definition,
             promptFile: stagedPrompt.file,
             worktreeDir: launchDir,
             secretsFile,
+            runner,
+            sandboxName,
         });
         const launchCmd = stageWorkspaceLaunchCommand(promptDir, launchCommand);
         log("Opening workspace...");

package/dist/lib/config.d.ts

@@ -15,6 +15,39 @@ export declare const AGENT_ANY_MODEL = "any";
  */
 export type WorkspaceKindSetting = "auto" | "cmux" | "tmux";
 export declare const WORKSPACE_KIND_SETTINGS: readonly WorkspaceKindSetting[];
+/**
+ * Concrete local isolation backend selected for a launch. `safehouse` is
+ * macOS-only (clearance HTTP-egress + sandbox profile); `sdx` is Docker
+ * Sandboxes (`sbx` CLI) — works on Linux and macOS and is the only known
+ * option that lets the agent use Docker safely without exposing the host
+ * socket; `none` is an explicit unsandboxed escape hatch.
+ */
+export type LocalRunner = "safehouse" | "sdx" | "none";
+/**
+ * User-facing local runner setting. `auto` resolves at launch time:
+ * macOS picks `safehouse`, Linux picks `sdx`. `none` is never picked
+ * implicitly.
+ */
+export type LocalRunnerSetting = LocalRunner | "auto";
+export declare const LOCAL_RUNNER_SETTINGS: readonly LocalRunnerSetting[];
+/**
+ * Per-model Docker Sandboxes (sdx) binding. Required at launch when
+ * `local.runner` resolves to `sdx` so groundcrew knows which sbx agent
+ * to address and how to seed the sandbox.
+ */
+export interface SandboxDefinition {
+    /** sbx agent name (e.g. "claude", "codex"). */
+    agent: string;
+    /** Optional `sbx run --template` value. */
+    template?: string;
+    /** Optional `sbx run --kit` values (each passed as a separate flag). */
+    kits?: string[];
+    /**
+     * Setup command run **inside** the sandbox before the agent exec.
+     * Defaults to `DEFAULT_SANDBOX_SETUP_COMMAND` when omitted.
+     */
+    setupCommand?: string;
+}
 export interface ModelDefinition {
     /**
      * Shell command launched for the model. Wrapped with Safehouse/clearance
@@ -32,6 +65,12 @@ export interface ModelDefinition {
             source?: string;
         };
     };
+    /**
+     * Docker Sandboxes binding. Required when `local.runner` resolves to
+     * `sdx` — pure additive: omitted models can still run under `safehouse`
+     * or `none` without surprise.
+     */
+    sandbox?: SandboxDefinition;
 }
 /**
  * User-facing model entry shape. Discriminated union so the type system
@@ -51,6 +90,14 @@ type UserModelDefinition = EnabledUserModelDefinition | DisabledUserModelDefinit
  * assumed to already have the right Node and npm versions.
  */
 export declare const DEFAULT_HOST_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
+/**
+ * Setup command run inside an sdx (Docker Sandboxes) sandbox before the
+ * agent process exec. Independent of the host setup — sandboxes typically
+ * lack Node tooling on first start, so we keep the recipe scoped to the
+ * common case of an npm-managed repo while still letting per-model
+ * `sandbox.setupCommand` override it for languages outside that path.
+ */
+export declare const DEFAULT_SANDBOX_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
 /**
  * Loose user-facing shape — what a `config.ts` file declares.
  * Fields with defaults are optional; only `linear.projectSlug` and the
@@ -107,6 +154,14 @@ export interface Config {
      * to fail loudly when the chosen backend is missing.
      */
     workspaceKind?: WorkspaceKindSetting;
+    /**
+     * Local isolation backend selector. Defaults to `"auto"` (macOS →
+     * safehouse, Linux → sdx). `"none"` is an explicit unsandboxed escape
+     * hatch — never selected implicitly.
+     */
+    local?: {
+        runner?: LocalRunnerSetting;
+    };
     logging?: {
         /**
          * Append-mode log file destination. `log()` and `logEvent()` tee here
@@ -158,6 +213,14 @@ export interface ResolvedConfig {
      * `auto` resolves to cmux when installed, else tmux.
      */
     workspaceKind: WorkspaceKindSetting;
+    /**
+     * Local isolation selection. The user-facing `auto` is preserved here
+     * so `localRunner.resolve()` can pick the platform default later — the
+     * resolver is the only place that knows the host capabilities.
+     */
+    local: {
+        runner: LocalRunnerSetting;
+    };
     logging: {
         file: string;
     };

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.js

@@ -17,11 +17,25 @@ export const WORKSPACE_KIND_SETTINGS = [
     "cmux",
     "tmux",
 ];
+export const LOCAL_RUNNER_SETTINGS = [
+    "auto",
+    "safehouse",
+    "sdx",
+    "none",
+];
 /**
  * Setup command run inside sibling worktrees on the host. The host is
  * assumed to already have the right Node and npm versions.
  */
 export const DEFAULT_HOST_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
+/**
+ * Setup command run inside an sdx (Docker Sandboxes) sandbox before the
+ * agent process exec. Independent of the host setup — sandboxes typically
+ * lack Node tooling on first start, so we keep the recipe scoped to the
+ * common case of an npm-managed repo while still letting per-model
+ * `sandbox.setupCommand` override it for languages outside that path.
+ */
+export const DEFAULT_SANDBOX_SETUP_COMMAND = "if [ -x .claude/setup.sh ]; then ./.claude/setup.sh --deps-only; elif [ -f .claude/setup.sh ] && command -v bash >/dev/null 2>&1; then bash .claude/setup.sh --deps-only; else npm clean-install; fi";
 const DEFAULT_STATUSES = {
     todo: "Todo",
     inProgress: "In Progress",
@@ -194,6 +208,43 @@ function normalizeWorkspaceKind(value, path) {
     }
     return value;
 }
+function isLocalRunnerSetting(value) {
+    return typeof value === "string" && LOCAL_RUNNER_SETTINGS.includes(value);
+}
+function normalizeLocalRunner(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isLocalRunnerSetting(value)) {
+        fail(`${path} must be one of ${LOCAL_RUNNER_SETTINGS.join(", ")} (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function normalizeSandbox(value, path) {
+    if (!isPlainObject(value)) {
+        fail(`${path} must be an object`);
+    }
+    const { agent, template, kits, setupCommand } = value;
+    requireString(agent, `${path}.agent`);
+    const trimmedAgent = agent.trim();
+    if (trimmedAgent.length === 0) {
+        fail(`${path}.agent must be a non-empty string (got ${JSON.stringify(agent)})`);
+    }
+    const sandbox = { agent: trimmedAgent };
+    const normalizedTemplate = normalizeOptionalString(template, `${path}.template`);
+    if (normalizedTemplate !== undefined) {
+        sandbox.template = normalizedTemplate;
+    }
+    const normalizedKits = normalizeOptionalStringArray(kits, `${path}.kits`);
+    if (normalizedKits !== undefined) {
+        sandbox.kits = normalizedKits;
+    }
+    const normalizedSetup = normalizeOptionalString(setupCommand, `${path}.setupCommand`);
+    if (normalizedSetup !== undefined) {
+        sandbox.setupCommand = normalizedSetup;
+    }
+    return sandbox;
+}
 function failIfLegacyModelKeys(name, override) {
     if (!isPlainObject(override)) {
         fail(`models.definitions.${name} must be an object`);
@@ -201,14 +252,11 @@ function failIfLegacyModelKeys(name, override) {
     if (Object.hasOwn(override, "isolation")) {
         fail(`models.definitions.${name}.isolation is no longer supported: per-model isolation is no longer supported`);
     }
-    if (Object.hasOwn(override, "sandbox")) {
-        fail(`models.definitions.${name}.sandbox is no longer supported: Docker Sandboxes are no longer supported`);
-    }
     if (Object.hasOwn(override, "disabled")) {
         if (override["disabled"] !== true) {
             fail(`models.definitions.${name}.disabled must be exactly \`true\` when set (got ${JSON.stringify(override["disabled"])})`);
         }
-        const conflicting = ["cmd", "color", "usage"].filter((key) => Object.hasOwn(override, key));
+        const conflicting = ["cmd", "color", "usage", "sandbox"].filter((key) => Object.hasOwn(override, key));
         if (conflicting.length > 0) {
             fail(`models.definitions.${name}: cannot combine \`disabled: true\` with other fields (${conflicting.join(", ")}). Either disable the model or override its fields, not both.`);
         }
@@ -258,7 +306,10 @@ function mergeDefinitions(user) {
         if (override.usage !== undefined) {
             candidate.usage = override.usage;
         }
-        const { cmd, color, usage } = candidate;
+        if (override.sandbox !== undefined) {
+            candidate.sandbox = normalizeSandbox(override.sandbox, `models.definitions.${name}.sandbox`);
+        }
+        const { cmd, color, usage, sandbox } = candidate;
         if (typeof cmd !== "string" || cmd.length === 0) {
             fail(`models.definitions.${name}.cmd must be a non-empty string`);
         }
@@ -269,6 +320,9 @@ function mergeDefinitions(user) {
         if (usage !== undefined) {
             definition.usage = usage;
         }
+        if (sandbox !== undefined) {
+            definition.sandbox = sandbox;
+        }
         merged[name] = definition;
     }
     return merged;
@@ -294,10 +348,14 @@ function applyDefaults(user) {
     requireString(user.linear.projectSlug, "linear.projectSlug");
     requireObject(user.workspace, "workspace");
     if (isPlainObject(user.models) && Object.hasOwn(user.models, "isolation")) {
-        fail("models.isolation is no longer supported: local isolation is always Safehouse; remove this key");
+        fail("models.isolation is no longer supported: set `local.runner` ('safehouse' | 'sdx' | 'none' | 'auto') instead");
     }
     if (Object.hasOwn(user, "remote")) {
-        fail("remote is no longer supported: groundcrew is macOS + Safehouse only; remove the remote block from your config");
+        fail("remote is no longer supported: groundcrew runs locally via safehouse/sdx/none; remove the remote block from your config");
+    }
+    const userLocal = user.local;
+    if (userLocal !== undefined && !isPlainObject(userLocal)) {
+        fail("local must be an object");
     }
     const slugId = extractSlugId(user.linear.projectSlug);
     if (slugId === undefined) {
@@ -323,6 +381,9 @@ function applyDefaults(user) {
             initial: user.prompts?.initial ?? DEFAULT_PROMPT_INITIAL,
         },
         workspaceKind: normalizeWorkspaceKind(user.workspaceKind, "workspaceKind") ?? "auto",
+        local: {
+            runner: normalizeLocalRunner(userLocal?.runner, "local.runner") ?? "auto",
+        },
         logging: {
             file: expandHome(normalizeOptionalString(user.logging?.file, "logging.file") ?? defaultLogFile()),
         },
@@ -379,6 +440,13 @@ function validate(config) {
             }
             requireString(codexbar.provider, `${usagePath}.codexbar.provider`);
         }
+        if (definition.sandbox !== undefined) {
+            requireString(definition.sandbox.agent, `models.definitions.${name}.sandbox.agent`);
+        }
+    }
+    /* v8 ignore next 5 @preserve -- normalizeLocalRunner rejects invalid strings before validate() runs; this is a belt-and-suspenders guard */
+    if (!LOCAL_RUNNER_SETTINGS.includes(config.local.runner)) {
+        fail(`local.runner must be one of ${LOCAL_RUNNER_SETTINGS.join(", ")} (got ${JSON.stringify(config.local.runner)})`);
     }
     // Disabled-default check must run before the generic "not a key" check so
     // the user gets the specific "is disabled" message instead of a stale-list

package/dist/lib/dockerSandbox.d.ts

@@ -0,0 +1,40 @@
+import type { SandboxDefinition } from "./config.ts";
+/**
+ * Derive a deterministic sbx sandbox name from the repository + model
+ * tuple so `crew sandbox auth <repo>` and the subsequent `crew local`
+ * launch agree on which sandbox to target. Lowercased and reduced to the
+ * sbx-safe charset (`a-z0-9.+-`) so unusual repo names still round-trip
+ * cleanly. Keep the prefix stable — doctor and teardown use it to
+ * identify groundcrew-owned sandboxes.
+ */
+export declare function sandboxNameFor(arguments_: {
+    repository: string;
+    model: string;
+}): string;
+/**
+ * Probe `sbx ls` to see whether a sandbox with `sandboxName` already
+ * exists. Used by `crew sandbox auth` to switch between create vs reuse
+ * branches without surfacing the raw sbx error on first run.
+ */
+export declare function sandboxExists(sandboxName: string, signal?: AbortSignal): Promise<boolean>;
+interface EnsureSandboxArguments {
+    sandboxName: string;
+    sandbox: SandboxDefinition;
+    /**
+     * Host path bound into the sandbox at the same path. Pass the workspace
+     * `projectDir` so all per-ticket worktrees (siblings of the bare repo
+     * clone) are visible to `sbx exec -w <worktreeDir>` after creation.
+     */
+    mountPath: string;
+}
+/**
+ * Idempotent guard: ensure a Docker Sandboxes container exists for the
+ * given repository + model. Probes `sbx ls`; if `sandboxName` is missing,
+ * calls `sbx create --name <name> [--template <t>] [--kit <k>]... <agent>
+ * <mountPath>` to provision it. First-time agent auth still happens inside
+ * the sandbox the first time `sbx exec` runs the agent — `create` only
+ * provisions the container, it does not attach.
+ */
+export declare function ensureSandbox(arguments_: EnsureSandboxArguments, signal?: AbortSignal): Promise<void>;
+export {};
+//# sourceMappingURL=dockerSandbox.d.ts.map

package/dist/lib/dockerSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dockerSandbox.d.ts","sourceRoot":"","sources":["../../src/lib/dockerSandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAMxF;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAM/F;AAED,UAAU,sBAAsB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,sBAAsB,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/lib/dockerSandbox.js

@@ -0,0 +1,58 @@
+import { runCommandAsync } from "./commandRunner.js";
+/**
+ * Derive a deterministic sbx sandbox name from the repository + model
+ * tuple so `crew sandbox auth <repo>` and the subsequent `crew local`
+ * launch agree on which sandbox to target. Lowercased and reduced to the
+ * sbx-safe charset (`a-z0-9.+-`) so unusual repo names still round-trip
+ * cleanly. Keep the prefix stable — doctor and teardown use it to
+ * identify groundcrew-owned sandboxes.
+ */
+export function sandboxNameFor(arguments_) {
+    const raw = `groundcrew-${arguments_.repository}-${arguments_.model}`.toLowerCase();
+    return raw
+        .replaceAll(/[^a-z0-9.+-]+/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-|-$/g, "");
+}
+/**
+ * Probe `sbx ls` to see whether a sandbox with `sandboxName` already
+ * exists. Used by `crew sandbox auth` to switch between create vs reuse
+ * branches without surfacing the raw sbx error on first run.
+ */
+export async function sandboxExists(sandboxName, signal) {
+    const out = signal === undefined
+        ? await runCommandAsync("sbx", ["ls"])
+        : await runCommandAsync("sbx", ["ls"], { signal });
+    return out.split("\n").some((line) => line.trim().split(/\s+/)[0] === sandboxName);
+}
+/**
+ * Idempotent guard: ensure a Docker Sandboxes container exists for the
+ * given repository + model. Probes `sbx ls`; if `sandboxName` is missing,
+ * calls `sbx create --name <name> [--template <t>] [--kit <k>]... <agent>
+ * <mountPath>` to provision it. First-time agent auth still happens inside
+ * the sandbox the first time `sbx exec` runs the agent — `create` only
+ * provisions the container, it does not attach.
+ */
+export async function ensureSandbox(arguments_, signal) {
+    if (await sandboxExists(arguments_.sandboxName, signal)) {
+        return;
+    }
+    const createArguments = ["create", "--name", arguments_.sandboxName];
+    if (arguments_.sandbox.template !== undefined) {
+        createArguments.push("--template", arguments_.sandbox.template);
+    }
+    for (const kit of arguments_.sandbox.kits ?? []) {
+        createArguments.push("--kit", kit);
+    }
+    createArguments.push(arguments_.sandbox.agent, arguments_.mountPath);
+    const options = signal === undefined ? {} : { signal };
+    try {
+        await runCommandAsync("sbx", createArguments, options);
+    }
+    catch (error) {
+        if (await sandboxExists(arguments_.sandboxName, signal)) {
+            return;
+        }
+        throw error;
+    }
+}

package/dist/lib/host.d.ts

@@ -6,18 +6,28 @@
 export interface HostCapabilities {
     /** True when the `safehouse` binary is on PATH. */
     hasSafehouse: boolean;
+    /** True when the `sbx` (Docker Sandboxes) binary is on PATH. */
+    hasSbx: boolean;
     /** True when the `cmux` binary is on PATH. */
     hasCmux: boolean;
     /** True when the `tmux` binary is on PATH. */
     hasTmux: boolean;
     /** True when the host platform is macOS. Safehouse is macOS-only. */
     isMacOS: boolean;
+    /** True when the host platform is Linux. */
+    isLinux: boolean;
     /**
      * True when the host platform is one Safehouse supports. Safehouse is
      * macOS-only at time of writing; local setup uses this to reject Linux
      * or WSL before creating a worktree.
      */
     isSafehouseSupported: boolean;
+    /**
+     * True when sdx (Docker Sandboxes) is supportable on this platform —
+     * sbx is published for both macOS and Linux, so this stays in sync with
+     * "macOS || Linux". WSL inherits Linux capabilities transparently.
+     */
+    isSdxSupported: boolean;
 }
 /**
  * Resolves a binary on PATH the same way `which` does. Returns the first

package/dist/lib/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/lib/host.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc1F;AAED,wBAAsB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc5F"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/lib/host.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc1F;AAED,wBAAsB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmB5F"}

package/dist/lib/host.js

@@ -3,7 +3,7 @@
  * current machine. Doctor and setup inject a capabilities object directly
  * so tests don't have to mock `which`.
  */
-import { platform } from "node:process";
+import process from "node:process";
 import { runCommandAsync } from "./commandRunner.js";
 /**
  * Resolves a binary on PATH the same way `which` does. Returns the first
@@ -26,17 +26,22 @@ export async function which(cmd, signal) {
     }
 }
 export async function detectHostCapabilities(signal) {
-    const isMacOS = platform === "darwin";
-    const [safehouse, cmux, tmux] = await Promise.all([
+    const isMacOS = process.platform === "darwin";
+    const isLinux = process.platform === "linux";
+    const [safehouse, sbx, cmux, tmux] = await Promise.all([
         which("safehouse", signal),
+        which("sbx", signal),
         which("cmux", signal),
         which("tmux", signal),
     ]);
     return {
         hasSafehouse: safehouse !== undefined,
+        hasSbx: sbx !== undefined,
         hasCmux: cmux !== undefined,
         hasTmux: tmux !== undefined,
         isMacOS,
+        isLinux,
         isSafehouseSupported: isMacOS,
+        isSdxSupported: isMacOS || isLinux,
     };
 }

package/dist/lib/launchCommand.d.ts

@@ -1,4 +1,4 @@
-import { type ModelDefinition } from "./config.ts";
+import { type LocalRunner, type ModelDefinition } from "./config.ts";
 export { shellSingleQuote } from "./shell.ts";
 /**
  * Resolve the shipped Safehouse proxy wrapper inside `@clipboard-health/clearance`
@@ -18,10 +18,24 @@ interface LaunchCommandArguments {
     /**
      * Optional path to a `KEY='value'` env file containing build-time
      * secrets (see `BUILD_SECRET_NAMES`). Sourced on the host shell before
-     * setup and always unset before exec'ing the agent so the agent process
-     * never inherits them.
+     * setup; for the sdx runner the names are propagated into the sandbox
+     * via `sbx exec -e KEY`. Always unset before exec'ing the agent so the
+     * agent process never inherits them.
      */
     secretsFile?: string | undefined;
+    /**
+     * Concrete local isolation backend chosen for this launch. Resolved
+     * from `config.local.runner` via `resolveLocalRunner` before this
+     * function is called — `auto` is never seen here.
+     */
+    runner: LocalRunner;
+    /**
+     * sbx sandbox name when `runner === "sdx"`. Derived by the caller from
+     * `sandboxNameFor({ repository, model })`. Required for sdx; ignored
+     * otherwise. Kept off the model definition so a model can launch under
+     * safehouse on one host and sdx on another without config edits.
+     */
+    sandboxName?: string | undefined;
 }
 /**
  * Build the shell command that runs inside the workspace. The prompt is

package/dist/lib/launchCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AA+BD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA2B7E"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAmCD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAK7E"}

package/dist/lib/launchCommand.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
-import { BUILD_SECRET_NAMES, DEFAULT_HOST_SETUP_COMMAND } from "./config.js";
+import { BUILD_SECRET_NAMES, DEFAULT_HOST_SETUP_COMMAND, DEFAULT_SANDBOX_SETUP_COMMAND, } from "./config.js";
 import { shellSingleQuote } from "./shell.js";
 export { shellSingleQuote } from "./shell.js";
 /**
@@ -28,7 +28,7 @@ const SAFEHOUSE_CLEARANCE_WRAPPER_PATH = resolveSafehouseClearancePath();
 function renderAgentCommand(arguments_) {
     return arguments_.agentCmd
         .replaceAll("{{worktree}}", shellSingleQuote(arguments_.worktreeDir))
-        .replaceAll("{{sandbox}}", shellSingleQuote(""));
+        .replaceAll("{{sandbox}}", shellSingleQuote(arguments_.sandboxName));
 }
 function setupWithStatusReporting(setupCommand) {
     return [
@@ -57,17 +57,23 @@ function unsetSecretsLine() {
  * prompt in hand.
  */
 export function buildLaunchCommand(arguments_) {
+    if (arguments_.runner === "sdx") {
+        return buildSdxLaunchCommand(arguments_);
+    }
+    return buildHostLaunchCommand(arguments_);
+}
+function buildHostLaunchCommand(arguments_) {
     const promptDir = dirname(arguments_.promptFile);
     const agentCmd = renderAgentCommand({
         agentCmd: arguments_.definition.cmd,
         worktreeDir: arguments_.worktreeDir,
+        sandboxName: "",
+    });
+    const wrapped = wrapAgentForHostRunner({
+        runner: arguments_.runner,
+        rawCmd: arguments_.definition.cmd,
+        agentCmd,
     });
-    // Skip the wrap if `cmd` already starts with `safehouse` so legacy
-    // configs don't double-wrap.
-    const cmdStartsWithSafehouse = /^safehouse(\s|$)/.test(arguments_.definition.cmd);
-    const wrapped = cmdStartsWithSafehouse
-        ? agentCmd
-        : [shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH), agentCmd].join(" ");
     const lines = [`cd ${shellSingleQuote(arguments_.worktreeDir)}`];
     if (arguments_.secretsFile !== undefined) {
         lines.push(sourceSecretsLine(arguments_.secretsFile));
@@ -79,3 +85,55 @@ export function buildLaunchCommand(arguments_) {
     lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec ${wrapped} "$_p"`);
     return lines.join(" && ");
 }
+function wrapAgentForHostRunner(arguments_) {
+    if (arguments_.runner === "none") {
+        return arguments_.agentCmd;
+    }
+    // buildLaunchCommand routes `sdx` through buildSdxLaunchCommand, so the
+    // only remaining shape here is `safehouse`. Treat the explicit branch as
+    // the safehouse wrap to keep this function readable; the `sdx` arm exists
+    // only to satisfy TS's exhaustiveness checker.
+    /* v8 ignore next 3 @preserve -- buildLaunchCommand short-circuits sdx before calling this helper */
+    if (arguments_.runner === "sdx") {
+        return arguments_.agentCmd;
+    }
+    // safehouse: skip the wrap if `cmd` already starts with `safehouse` so
+    // legacy configs don't double-wrap.
+    const cmdStartsWithSafehouse = /^safehouse(\s|$)/.test(arguments_.rawCmd);
+    if (cmdStartsWithSafehouse) {
+        return arguments_.agentCmd;
+    }
+    return [shellSingleQuote(SAFEHOUSE_CLEARANCE_WRAPPER_PATH), arguments_.agentCmd].join(" ");
+}
+function buildSdxLaunchCommand(arguments_) {
+    /* v8 ignore next 5 @preserve -- setupWorkspace passes sandboxName + sandbox config when picking sdx; missing fields are programmer errors */
+    if (arguments_.sandboxName === undefined || arguments_.definition.sandbox === undefined) {
+        throw new Error("buildLaunchCommand: runner='sdx' requires sandboxName and a model `sandbox` config block (set sandbox.agent on the model in config.ts).");
+    }
+    const promptDir = dirname(arguments_.promptFile);
+    const agentCmd = renderAgentCommand({
+        agentCmd: arguments_.definition.cmd,
+        worktreeDir: arguments_.worktreeDir,
+        sandboxName: arguments_.sandboxName,
+    });
+    const setupCommand = arguments_.definition.sandbox.setupCommand ?? DEFAULT_SANDBOX_SETUP_COMMAND;
+    const innerParts = [setupWithStatusReporting(setupCommand)];
+    if (arguments_.secretsFile !== undefined) {
+        innerParts.push(unsetSecretsLine());
+    }
+    innerParts.push(`exec ${agentCmd} "$@"`);
+    const innerCommand = innerParts.join("; ");
+    // Passthrough form (`-e KEY` without `=VALUE`): sbx reads each value
+    // from its own env at invocation time — populated by sourceSecretsLine
+    // a few lines up. Avoids `-e KEY="$KEY"`, which would embed the value
+    // in argv and break on `"`, `$`, or backticks in the token.
+    const sbxEnvironmentFlags = arguments_.secretsFile === undefined
+        ? ""
+        : `${BUILD_SECRET_NAMES.map((name) => `-e ${name}`).join(" ")} `;
+    const lines = [];
+    if (arguments_.secretsFile !== undefined) {
+        lines.push(sourceSecretsLine(arguments_.secretsFile));
+    }
+    lines.push(`_p=$(cat ${shellSingleQuote(arguments_.promptFile)})`, `rm -rf ${shellSingleQuote(promptDir)}`, `exec sbx exec -it ${sbxEnvironmentFlags}-w ${shellSingleQuote(arguments_.worktreeDir)} ${shellSingleQuote(arguments_.sandboxName)} sh -lc ${shellSingleQuote(innerCommand)} sh "$_p"`);
+    return lines.join(" && ");
+}

package/dist/lib/localRunner.d.ts

@@ -1,3 +1,24 @@
+import type { LocalRunner, LocalRunnerSetting } from "./config.ts";
 import type { HostCapabilities } from "./host.ts";
-export declare function assertLocalRunnerRequirements(host: HostCapabilities): void;
+/**
+ * Resolve `local.runner` from config + host capabilities into a concrete
+ * backend. `auto` defaults to safehouse on macOS and sdx on Linux — both
+ * are the deny-first paths for their platform. `none` and the explicit
+ * names pass through unchanged so users always get exactly what they
+ * asked for. Pure: takes everything it needs as arguments so the
+ * dispatcher can test platform pivots without touching real hosts.
+ */
+export declare function resolveLocalRunner(setting: LocalRunnerSetting, host: HostCapabilities): LocalRunner;
+/**
+ * Verify the host can run the chosen local isolation backend before we
+ * create a worktree. The runner has already been resolved from
+ * `config.local.runner` (via `resolveLocalRunner`), so `auto` never gets
+ * here — the caller passes `safehouse`, `sdx`, or `none`.
+ *
+ * `none` is a deliberately unsafe escape hatch. It is never selected
+ * implicitly (`auto` picks `safehouse`/`sdx`); when the user has set it
+ * explicitly, this helper logs a single warning so the unsandboxed launch
+ * is visible in groundcrew's log, but does not throw.
+ */
+export declare function assertLocalRunnerRequirements(host: HostCapabilities, runner: LocalRunner): void;
 //# sourceMappingURL=localRunner.d.ts.map

package/dist/lib/localRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"localRunner.d.ts","sourceRoot":"","sources":["../../src/lib/localRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAS1E"}
+{"version":3,"file":"localRunner.d.ts","sourceRoot":"","sources":["../../src/lib/localRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,gBAAgB,GACrB,WAAW,CAQb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CA6B/F"}

package/dist/lib/localRunner.js

@@ -1,8 +1,51 @@
-export function assertLocalRunnerRequirements(host) {
-    if (!host.isSafehouseSupported) {
-        throw new Error("groundcrew runs require macOS with Safehouse. Linux/WSL is not supported.");
+import { log } from "./util.js";
+/**
+ * Resolve `local.runner` from config + host capabilities into a concrete
+ * backend. `auto` defaults to safehouse on macOS and sdx on Linux — both
+ * are the deny-first paths for their platform. `none` and the explicit
+ * names pass through unchanged so users always get exactly what they
+ * asked for. Pure: takes everything it needs as arguments so the
+ * dispatcher can test platform pivots without touching real hosts.
+ */
+export function resolveLocalRunner(setting, host) {
+    if (setting !== "auto") {
+        return setting;
     }
-    if (!host.hasSafehouse) {
-        throw new Error("groundcrew runs require `safehouse` on PATH. Install Safehouse from https://agent-safehouse.dev/ and retry.");
+    // macOS → safehouse; everything else (Linux/WSL, exotic platforms) → sdx.
+    // `assertLocalRunnerRequirements` then enforces sdx's platform/binary
+    // preconditions and surfaces a precise error on truly unsupported hosts.
+    return host.isMacOS ? "safehouse" : "sdx";
+}
+/**
+ * Verify the host can run the chosen local isolation backend before we
+ * create a worktree. The runner has already been resolved from
+ * `config.local.runner` (via `resolveLocalRunner`), so `auto` never gets
+ * here — the caller passes `safehouse`, `sdx`, or `none`.
+ *
+ * `none` is a deliberately unsafe escape hatch. It is never selected
+ * implicitly (`auto` picks `safehouse`/`sdx`); when the user has set it
+ * explicitly, this helper logs a single warning so the unsandboxed launch
+ * is visible in groundcrew's log, but does not throw.
+ */
+export function assertLocalRunnerRequirements(host, runner) {
+    if (runner === "safehouse") {
+        if (!host.isSafehouseSupported) {
+            throw new Error("Local groundcrew runs with the safehouse runner require macOS. On Linux/WSL, set local.runner to 'sdx' (default) or 'auto'.");
+        }
+        if (!host.hasSafehouse) {
+            throw new Error("Local groundcrew runs require `safehouse` on PATH. Install Safehouse from https://agent-safehouse.dev/ and retry.");
+        }
+        return;
+    }
+    if (runner === "sdx") {
+        if (!host.isSdxSupported) {
+            throw new Error("Local groundcrew runs with the sdx runner require macOS or Linux.");
+        }
+        if (!host.hasSbx) {
+            throw new Error("Local groundcrew runs with the sdx runner require `sbx` (Docker Sandboxes) on PATH. Install from https://docs.docker.com/sandboxes/ and retry.");
+        }
+        return;
     }
+    // runner === "none"
+    log("WARNING: local.runner='none' — agent process will run on the host without sandboxing. Only use this when you understand the implications.");
 }

package/dist/lib/workspaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AA+L7C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AA+ND,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SAAS,cAAc,QAAQ,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/lib/workspaces.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAI1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgU7C,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,oBAAoB,CAAC;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,mBAAmB,CAUtF;AA+ND,iBAAe,eAAe,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,eAAO,MAAM,UAAU;IACf,IAAI,SAAS,cAAc,QAAQ,QAAQ,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvF,KAAK;IACC,KAAK,SAAS,cAAc,QAAQ,MAAM,WAAW,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,UAAU,SACN,cAAc,QAChB,MAAM,WACH,WAAW,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;CAI5C,CAAC"}

package/dist/lib/workspaces.js

@@ -6,6 +6,7 @@
  */
 import { runCommandAsync } from "./commandRunner.js";
 import { detectHostCapabilities } from "./host.js";
+import { shellSingleQuote } from "./shell.js";
 import { errorMessage, log, readEnvironmentVariable } from "./util.js";
 async function runWorkspaceCommand(command, arguments_, signal) {
     return signal === undefined
@@ -24,23 +25,30 @@ function parseCmuxList(output) {
         if (typeof ws.title !== "string" || ws.title.length === 0) {
             continue;
         }
-        items.push({ title: ws.title, ref: pickCmuxRef({ ...ws, title: ws.title }) });
+        const id = pickCmuxId(ws);
+        if (id === undefined) {
+            log(`cmux list-workspaces returned workspace "${ws.title}" without a usable id or ref; skipping`);
+            continue;
+        }
+        items.push({ title: ws.title, id });
     }
     return items;
 }
 /**
- * Pick the most-specific identifier cmux returned for this workspace.
- * Caller has already verified `title` is non-empty, so the title fallback
- * is always defined.
+ * The stable workspace handle cmux v2 expects in JSON-RPC params. Prefer
+ * the UUID; fall back to the legacy `workspace:N` short ref when older
+ * cmux builds don't surface it. Returns `undefined` when neither is
+ * available — cmux v2 `workspace.close` rejects titles, so we must never
+ * forward `title` as a workspace handle.
  */
-function pickCmuxRef(ws) {
-    if (typeof ws.ref === "string" && ws.ref.length > 0) {
-        return ws.ref;
-    }
+function pickCmuxId(ws) {
     if (typeof ws.id === "string" && ws.id.length > 0) {
         return ws.id;
     }
-    return ws.title;
+    if (typeof ws.ref === "string" && ws.ref.length > 0) {
+        return ws.ref;
+    }
+    return undefined;
 }
 async function listCmuxRaw(signal) {
     try {
@@ -54,13 +62,17 @@ async function listCmuxRaw(signal) {
         return undefined;
     }
 }
-function extractCmuxOpenRef(output) {
+function extractCmuxOpenId(output) {
     try {
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json prints a workspace ref/id object
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json prints a workspace_id/ref object
         const parsed = JSON.parse(output);
-        const candidate = parsed.ref ?? parsed.id ?? "";
-        if (candidate.length > 0) {
-            return candidate;
+        const uuid = parsed.workspace_id ?? parsed.id ?? "";
+        if (uuid.length > 0) {
+            return uuid;
+        }
+        const ref = parsed.workspace_ref ?? parsed.ref ?? "";
+        if (ref.length > 0) {
+            return ref;
         }
     }
     catch {
@@ -69,7 +81,91 @@ function extractCmuxOpenRef(output) {
     const match = /workspace:\d+/.exec(output);
     return match ? match[0] : undefined;
 }
-async function applyCmuxStatus(ref, status, signal) {
+/**
+ * Inspect `cmux current-workspace`. When groundcrew is itself launched
+ * inside a cmux SSH workspace, `workspace.create` lands the new workspace
+ * on the local (macOS) cmux app rather than the remote where the agent's
+ * worktree lives. We can't replicate cmux's full SSH bootstrap
+ * (relay_port, daemon, etc.) from the remote side, so we instead wrap the
+ * agent launch command in a plain `ssh` to the same destination. Returns
+ * `undefined` when there is nothing to inherit, leaving callers free to
+ * launch locally as usual.
+ */
+async function probeCurrentCmuxRemote(signal) {
+    if (readEnvironmentVariable("CMUX_WORKSPACE_ID") === undefined) {
+        return undefined;
+    }
+    let output;
+    try {
+        output = await runWorkspaceCommand("cmux", ["--json", "current-workspace"], signal);
+    }
+    catch (error) {
+        if (isSignalAborted(signal)) {
+            throw error;
+        }
+        // CMUX_WORKSPACE_ID is set, so we are inside a cmux workspace and a
+        // probe failure means we cannot tell whether this is an SSH context.
+        // Silently degrading to the local path would point cmux at a working
+        // directory that lives on a remote host; surface the failure instead
+        // so the caller can roll the worktree back rather than launch into
+        // the void.
+        throw new Error(`cmux current-workspace probe failed while CMUX_WORKSPACE_ID is set: ${errorMessage(error)}`, { cause: error });
+    }
+    try {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cmux --json current-workspace shape per v2 API
+        const parsed = JSON.parse(output);
+        const remote = parsed.workspace?.remote;
+        if (remote === undefined ||
+            remote.connected !== true ||
+            remote.transport !== "ssh" ||
+            typeof remote.destination !== "string" ||
+            remote.destination.length === 0) {
+            return undefined;
+        }
+        const inherited = { destination: remote.destination };
+        if (typeof remote.port === "number") {
+            inherited.port = remote.port;
+        }
+        if (typeof remote.identity_file === "string" && remote.identity_file.length > 0) {
+            inherited.identity_file = remote.identity_file;
+        }
+        if (Array.isArray(remote.ssh_options) && remote.ssh_options.length > 0) {
+            inherited.ssh_options = remote.ssh_options;
+        }
+        return inherited;
+    }
+    catch (error) {
+        // Same reasoning as the command-failure branch above: with
+        // CMUX_WORKSPACE_ID set, malformed JSON means we cannot decide
+        // between local and SSH context, so refuse rather than silently
+        // launching at the wrong working directory.
+        throw new Error(`cmux current-workspace returned malformed output while CMUX_WORKSPACE_ID is set: ${errorMessage(error)}`, { cause: error });
+    }
+}
+/**
+ * Compose an `ssh -t <destination> -- <cd && cmd>` invocation that lands
+ * a new cmux workspace's terminal on the same SSH remote where
+ * groundcrew is running. Path-bearing fields (`cwd`, the launch script
+ * inside `command`) stay valid because the remote shell evaluates them.
+ * The outermost return value is a single shell string suitable for
+ * `cmux new-workspace --command`.
+ */
+function buildSshWrappedCommand(spec, remote) {
+    const remoteShell = `cd ${shellSingleQuote(spec.cwd)} && ${spec.command}`;
+    const sshTokens = ["ssh", "-t"];
+    if (remote.port !== undefined) {
+        sshTokens.push("-p", String(remote.port));
+    }
+    if (remote.identity_file !== undefined) {
+        sshTokens.push("-i", shellSingleQuote(remote.identity_file));
+    }
+    for (const option of remote.ssh_options ?? []) {
+        sshTokens.push("-o", shellSingleQuote(option));
+    }
+    sshTokens.push(shellSingleQuote(remote.destination), "--", shellSingleQuote(remoteShell));
+    return sshTokens.join(" ");
+}
+async function applyCmuxStatus(workspaceId, status, signal) {
     const arguments_ = ["set-status", "model", status.text];
     if (status.icon !== undefined) {
         arguments_.push("--icon", status.icon);
@@ -77,41 +173,40 @@ async function applyCmuxStatus(ref, status, signal) {
     if (status.color !== undefined) {
         arguments_.push("--color", status.color);
     }
-    arguments_.push("--workspace", ref);
+    arguments_.push("--workspace", workspaceId);
     await runWorkspaceCommand("cmux", arguments_, signal);
 }
-async function closeCmuxWorkspace(refOrName, signal) {
-    await runWorkspaceCommand("cmux", ["close-workspace", "--workspace", refOrName], signal);
+async function closeCmuxWorkspace(workspaceId, signal) {
+    await runWorkspaceCommand("cmux", ["close-workspace", "--workspace", workspaceId], signal);
 }
 const cmuxAdapter = {
     async open(spec, signal) {
-        const output = await runWorkspaceCommand("cmux", [
-            "--json",
-            "new-workspace",
-            "--name",
-            spec.name,
-            "--cwd",
-            spec.cwd,
-            "--command",
-            spec.command,
-        ], signal);
-        const ref = extractCmuxOpenRef(output);
-        if (ref === undefined) {
+        const inheritedRemote = await probeCurrentCmuxRemote(signal);
+        const newWorkspaceArguments = ["--json", "new-workspace", "--name", spec.name];
+        if (inheritedRemote === undefined) {
+            newWorkspaceArguments.push("--working-directory", spec.cwd, "--command", spec.command);
+        }
+        else {
+            // Skip --working-directory: the path is on the SSH remote and would
+            // fall back to $HOME (macOS) when cmux tries to chdir locally. The
+            // wrapped ssh command does its own `cd` on the remote side.
+            newWorkspaceArguments.push("--command", buildSshWrappedCommand(spec, inheritedRemote));
+        }
+        const output = await runWorkspaceCommand("cmux", newWorkspaceArguments, signal);
+        const workspaceId = extractCmuxOpenId(output);
+        if (workspaceId === undefined) {
             log(`cmux new-workspace returned unrecognized output for ${spec.name}; if a workspace was created, run \`cmux close-workspace\` manually.`);
             throw new Error(`Unexpected cmux output: ${output}`);
         }
         if (spec.status !== undefined) {
             try {
-                await applyCmuxStatus(ref, spec.status, signal);
+                await applyCmuxStatus(workspaceId, spec.status, signal);
             }
             catch (error) {
-                try {
-                    await closeCmuxWorkspace(ref, signal);
-                }
-                catch (closeError) {
-                    log(`cmux close-workspace failed for ${spec.name}: ${errorMessage(closeError)}`);
-                }
-                throw error;
+                // v2 cmux builds may not implement `set-status`; status pills are
+                // a nice-to-have, not load-bearing. Log and keep the workspace
+                // rather than tearing down a successful launch.
+                log(`cmux set-status failed for ${spec.name} (continuing): ${errorMessage(error)}`);
             }
         }
     },
@@ -122,7 +217,10 @@ const cmuxAdapter = {
     async close(name, signal) {
         const raw = await listCmuxRaw(signal);
         if (raw === undefined) {
-            await closeCmuxWorkspace(name, signal);
+            // cmux v2 `workspace.close` rejects titles, so forwarding `name`
+            // would always fail. The list failure has already been logged by
+            // `listCmuxRaw`; bail rather than guarantee a downstream error.
+            log(`cmux close-workspace skipped for ${name}: list-workspaces failed, no usable id`);
             return;
         }
         const match = raw.find((ws) => ws.title === name);
@@ -130,7 +228,7 @@ const cmuxAdapter = {
             return;
         }
         try {
-            await closeCmuxWorkspace(match.ref, signal);
+            await closeCmuxWorkspace(match.id, signal);
         }
         catch (error) {
             if (isSignalAborted(signal)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",