feat(client): backend runtime: container mode (#249 PR B) (#252)

* feat(client): backend runtime: host|container + SpawnAdapter (#249 PR B)

Adds the bridge-client side of the external-runtime profile that
PR A (#251) seeded the image for. claude / codex backends gain a
`runtime: 'host' | 'container'` option (config + CLI flag). In
container mode the agent CLI runs inside a long-lived vicoop-runtime
container the bridge client orchestrates via `docker exec`, instead
of being spawned as a host child process.

Key pieces:

- RuntimeContainer (runtime-container.ts) owns per-backend container
  lifecycle: docker daemon ping (no-fallback per Decision §6),
  image pull, named volume provisioning for agents / creds / sessions
  (Decisions §4 + §5), container create with --restart unless-stopped
  + NET_ADMIN/NET_RAW, reuse on bridge-client restart, explicit stop
  on shutdown.
- SpawnAdapter (spawn-adapter.ts) wraps both host (child_process.spawn)
  and docker-exec implementations in a SpawnFn signature that
  structurally satisfies the existing ClaudeSpawnFn / AppServerSpawnFn,
  so backend internals stay unaware of mode.
- pickBackend() is now async and routes claude / codex through
  resolveRuntime() which boots a RuntimeContainer when runtime ===
  'container' and injects a docker-exec spawn into the factory.
  Backend.stop() is wrapped to also stop the runtime container.
- dockerode (+ @types/dockerode) become runtime deps (#249 Decision §1).

Tests: 9 new (runtime-container 6, spawn-adapter 3). Full client
suite at 479 → 488, no regressions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(client/runtime): resolve docker socket from current docker context

dockerode's zero-arg constructor only honors \$DOCKER_HOST and falls
back to /var/run/docker.sock. That misses the common macOS reality
where colima / orbstack / rancher-desktop publish their socket under
\$HOME and wire the `docker` CLI via `docker context`. dockerode
doesn't read docker contexts itself, so without this resolver every
container-mode bridge client on those setups failed with
`ENOENT /var/run/docker.sock` despite `docker ps` working fine.

resolveDockerOptions() honors \$DOCKER_HOST first (returns undefined
so dockerode parses it), otherwise reads ~/.docker/config.json's
currentContext, derives the meta-file path from sha256(context name),
and pulls Endpoints.docker.Host out. unix:// becomes socketPath;
tcp:// becomes { host, port, protocol }. Unrecognized values fall
through to dockerode's default.

Verified end-to-end against the published vicoop-runtime image on a
colima host: bridge client starts, runtime container boots, named
volumes provisioned, WS hello + agent register succeed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(runtime-image): add bubblewrap + socat for claude sandbox

claude 2.1.x's per-tool-call sandbox runtime requires bwrap and
socat; without them the CLI exits 1 with "sandbox.failIfUnavailable
is set — refusing to start without a working sandbox" on the first
task. Surfaced during PR #252 e2e (#249 PR B) against the claude
spawn path. ~5MB combined, mirrors what anthropic's reference
devcontainer ships.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(client/runtime): await runtime container stop on SIGINT/SIGTERM

Before this, withRuntimeStop() folded runtime.stop() into the
backend's sync Backend.stop() as fire-and-forget. Result: the docker
stop API call was in-flight when process.exit ran, so the container
stayed Up after the bridge client exited. The next start cycle
silently reused it (good for the unless-stopped recovery path), but
an explicit shutdown observably leaving the container alive is
misleading and complicates operator mental models.

pickBackend now returns { backend, shutdown? } separately. Backend's
sync stop() stays untouched (its contract — kill a child, close a
socket, return immediately — still fits). The async shutdown hook
lives outside the Backend interface and runs from the signal
handler:

  SIGINT/SIGTERM
    → client.stop()             (sync, best-effort, as before)
    → await runWithShutdownTimeout(shutdown)
                                (caps at 15s so a wedged docker
                                 socket cannot pin the daemon)
    → process.exit(0)

A second signal short-circuits to exit(130) so an impatient operator
ctrl-c'ing twice always gets out.

Verified locally: tsx packages/client/src/cli.ts --codex-runtime
container; SIGTERM; container goes Exited (143) within docker's
grace window. host-mode backends are unaffected (no shutdown hook
to await).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(runtime): drop bwrap/socat, disable claude sandbox in container mode

The previous commit added bubblewrap + socat to the runtime image so
claude's per-tool-call sandbox could initialize. That worked, but
the outer container itself already isolates the agent (per-backend
named volumes, init-firewall.sh outbound allowlist, NET_ADMIN/NET_RAW
held by the entrypoint only). Stacking bwrap inside that container
double-isolates without a real security gain and balloons the image
for no operational benefit.

Cleaner shape:

- container/runtime/Dockerfile drops bubblewrap + socat. The runtime
  image stays minimal and the comment block documents the
  intentional omission so the next person reading the apt list
  doesn't add them back.
- packages/client/src/cli.ts threads container-mode-aware settings
  into the claude factory: `disableClaudeSandboxGuard()` merges
  `sandbox.failIfUnavailable: false` over the operator's settings
  only when runtime === 'container'. The backend (claude.ts) stays
  unaware of mode — pickBackend keeps that boundary clean. Host-mode
  claude is unaffected; its sandbox keeps working as before.

Verified end-to-end against the rebuilt image: claude path completes
a task in ~6s, SIGTERM gracefully stops the container.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(client/runtime): default codex sandbox to danger-full-access in container mode

Mirrors the same reasoning as claude's sandbox guard removal: the
outer container's isolation already caps what the agent can reach
(named-volume creds, init-firewall.sh egress allowlist, no NET_ADMIN
held by the agent process), so codex's own host-process sandbox is
redundant. In host mode codex's default 'read-only' is the right
safety floor; in container mode that default actively blocks the
agent from writing /workspace or running bash, which is exactly
what an operator running an agent inside a sandbox would expect to
work.

pickBackend's codex case now lifts the default to 'danger-full-access'
only when runtime === 'container' AND the operator did not explicitly
pick a sandbox via --codex-sandbox / config. Explicit values still
win, so belt-and-suspenders setups keep working.

Verified end-to-end against the runtime container: codex writes
/tmp/sandbox-test.txt and reads it back ("hello from container"),
SIGTERM cleanly stops the container.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: longfin

.changeset/external-runtime-spawn.md

@@ -0,0 +1,53 @@
+---
+'@vicoop-bridge/client': minor
+---
+
+Add `runtime: 'host' | 'container'` to the claude and codex backends
+(#249 PR B). This is the bridge-client side of the external-runtime
+profile landed in PR A (#251) — when an operator opts in, the agent
+CLI runs inside a long-lived `vicoop-runtime` container the bridge
+client orchestrates via `docker exec`, instead of being spawned as a
+host child process.
+
+New surface:
+
+- Config: `backends.claude.runtime` / `backends.codex.runtime` accept
+  `'host'` (default) or `'container'`.
+- CLI flags: `--claude-runtime host|container`, `--codex-runtime host|container`.
+  Standard precedence (flag > config) applies.
+- A `RuntimeContainer` module (`src/runtime-container.ts`) owns the
+  per-backend lifecycle: docker daemon ping, image pull, named-volume
+  provisioning (`vicoop-agents-<kind>`, `vicoop-creds-<kind>`,
+  `vicoop-sessions-<kind>`), container create with
+  `--restart unless-stopped` + `NET_ADMIN/NET_RAW`, reuse of an
+  existing container on bridge-client restart, and an explicit stop
+  on shutdown.
+- A `SpawnAdapter` module (`src/spawn-adapter.ts`) presents the
+  existing `ClaudeSpawnFn` / `AppServerSpawnFn` shape regardless of
+  mode. The host implementation is the same `node:child_process.spawn`
+  the backends use today; the container implementation runs the
+  command via `docker exec` inside the runtime container and bridges
+  stdin/stdout/stderr to PassThrough streams so backends see a normal
+  child-handle.
+- `dockerode` is a new runtime dependency (#249 Decision §1).
+
+Decisions reflected (#249 §Decisions):
+
+- §1 dockerode (programmatic API, not shell-out).
+- §2 `--restart unless-stopped` + bridge-client-side reuse on restart.
+- §3 Per-backend long-lived only; no per-context runtime.
+- §4 Creds in a container-only named volume — the host's `~/.claude`
+  never enters the container.
+- §5 Sessions volume mounted into the container so claude/codex
+  session resume survives container re-creation.
+- §6 No docker daemon → explicit error from `RuntimeContainer.start()`
+  with a "switch to runtime: 'host' or start docker" hint; no
+  fallback.
+- §8 The two backend kinds keep their identity; runtime mode is the
+  `runtime` field, and backend internals stay unaware of it.
+
+Out of scope (separate work):
+
+- Per-context workspace branching (today the host bind-mount is whole).
+- `vicoop-client backend init` operator-UX subcommand (PR C of #249).
+- Bundled-direct image publishing (still off per #250).

container/runtime/Dockerfile

@@ -37,6 +37,16 @@ ENV VICOOP_RUNTIME_IMAGE=$VICOOP_RUNTIME_IMAGE
 #   - tini: PID-1 reaper. agent CLI subprocesses spawn other children
 #     (e.g. claude code -> bash); without tini we leak zombies.
 #   - iptables, ipset, dnsutils, iproute2: init-firewall.sh
+#
+# Intentionally NOT installed: bubblewrap / socat. claude code uses
+# them to sandbox each tool call from the host. In the external-
+# runtime profile the outer container already provides isolation
+# (per-backend named volumes + init-firewall.sh egress allowlist),
+# so layering bwrap inside that container would double-isolate at
+# noticeable image cost without a security benefit. The bridge-client
+# side disables claude's sandbox guard via `sandbox.failIfUnavailable
+# = false` only when runtime === 'container'; host-mode claude keeps
+# its sandbox unchanged.
 RUN apt-get update \
  && apt-get install -y --no-install-recommends \
       ca-certificates curl git jq openssh-client tini \

packages/client/package.json

@@ -24,10 +24,12 @@
     "@optique/core": "1.0.2",
     "@optique/run": "1.0.2",
     "@vicoop-bridge/protocol": "workspace:*",
+    "dockerode": "^5.0.0",
     "ws": "^8.18.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/dockerode": "^4.0.1",
     "@types/ws": "^8.5.13"
   }
 }

packages/client/src/cli-args.ts

@@ -10,7 +10,7 @@ import { choice, integer, string } from '@optique/core/valueparser';
 import { parse } from '@optique/core/parser';
 import { formatMessage } from '@optique/core/message';
 import type { InferValue } from '@optique/core/parser';
-import type { ClientConfig, BackendConfigs } from './config.js';
+import type { ClientConfig, BackendConfigs, BackendRuntime } from './config.js';
 
 // Public bridge URL baked in so a fresh install on the public deployment
 // needs zero flags. Self-hosters override via --server / config.json. The
@@ -31,6 +31,8 @@ export type CodexSandboxMode = (typeof SANDBOX_MODES)[number];
 const BACKEND_KINDS = ['echo', 'openclaw', 'claude', 'codex', 'vicoop-codex'] as const;
 export type BackendKind = (typeof BACKEND_KINDS)[number];
 
+const BACKEND_RUNTIMES = ['host', 'container'] as const;
+
 // Optique daemon-mode grammar. Every operator-tunable knob is a flag here,
 // including the ones that used to be env-only (CLAUDE_CWD, CODEX_SANDBOX_MODE,
 // OPENCLAW_*) — see issue #189 §1. `optional()` everywhere because the
@@ -77,6 +79,9 @@ export const daemonFlagsFields = {
   claudeSettingsFile: optional(option('--claude-settings-file', string({ metavar: 'PATH' }), {
     description: message`Path to a JSON file used as Claude \`--settings\`.`,
   })),
+  claudeRuntime: optional(option('--claude-runtime', choice([...BACKEND_RUNTIMES]), {
+    description: message`Where to run \`claude\`. \`host\` (default) spawns on the bridge-client host; \`container\` runs inside a vicoop-runtime container the bridge client orchestrates (#249).`,
+  })),
 
   // Backend-specific (Codex)
   codexCwd: optional(option('--codex-cwd', string({ metavar: 'PATH' }), {
@@ -85,6 +90,9 @@ export const daemonFlagsFields = {
   codexSandbox: optional(option('--codex-sandbox', choice([...SANDBOX_MODES]), {
     description: message`Codex sandbox mode.`,
   })),
+  codexRuntime: optional(option('--codex-runtime', choice([...BACKEND_RUNTIMES]), {
+    description: message`Where to run \`codex\`. \`host\` (default) spawns on the bridge-client host; \`container\` runs inside a vicoop-runtime container the bridge client orchestrates (#249).`,
+  })),
 
   // Backend-specific (OpenClaw)
   openclawGateway: optional(option('--openclaw-gateway', string({ metavar: 'WS_URL' }), {
@@ -123,8 +131,10 @@ export interface DaemonArgs {
   // env when set; merge logic in cli.ts threads them into backend factories.
   claudeCwd?: string;
   claudeSettingsFile?: string;
+  claudeRuntime?: BackendRuntime;
   codexCwd?: string;
   codexSandbox?: CodexSandboxMode;
+  codexRuntime?: BackendRuntime;
   openclawGateway?: string;
   openclawGatewayToken?: string;
   openclawAgent?: string;
@@ -200,9 +210,11 @@ export function mergeClientArgs(
     backends: config.backends,
     claudeCwd: pick(flags.claudeCwd) || backends.claude?.cwd || undefined,
     claudeSettingsFile: pick(flags.claudeSettingsFile) || undefined,
+    claudeRuntime: flags.claudeRuntime ?? backends.claude?.runtime,
     codexCwd: pick(flags.codexCwd) || backends.codex?.cwd || undefined,
     codexSandbox:
       flags.codexSandbox ?? pickSandbox(backends.codex?.sandbox_mode),
+    codexRuntime: flags.codexRuntime ?? backends.codex?.runtime,
     openclawGateway:
       pick(flags.openclawGateway) || backends.openclaw?.gateway_url || undefined,
     openclawGatewayToken: