Optional Docker sandbox: whole-skvm-in-container via --sandbox

[lec77]

Linked issue

Closes #30

Summary

Adds an opt-in --sandbox flag that runs the entire skvm process inside an ephemeral Docker container, instead of containing execution per-adapter. Default behaviour is unchanged — without --sandbox, skvm runs on the host exactly as before. Raising the containment boundary above the adapter layer means adapter code is untouched and the per-surface complexity explored earlier (per-CLI HOME mounts, env-var flips, per-surface network defaults) disappears.

Changes

Launcher (new src/launcher/)

• index.ts — runLauncher(): composes mounts/env/image, a hardened docker run argv, then execs docker. Parses --mount-extra, --debug-sandbox (key-redacted), --docker-image, --docker-network.
• path-flags.ts — enumerates every path-shaped CLI flag with {kind, mode}, including comma-separated list flags.
• mounts.ts — three default mounts (/workspace, /skvm-cache, /skvm-data) plus dynamic /extra/<idx>/ mounts for out-of-root paths, with path-prefix dedup and longest-prefix root matching.
• env.ts — proxy passthrough, SKVM_CACHE/HOME markers, per-route key injection (SKVM_ROUTE_<id>_KEY), route-match collision detection.
• config-sanitize.ts — writes a key-stripped config the container mounts, so cat skvm.config.json inside the container exposes no secrets.
• image.ts — hybrid resolve: pull ghcr.io/sjtu-ipads/skvm-sandbox:<version>, fall back to a printed local docker build command.
• docker-argv.ts — --cap-drop=ALL, no-new-privileges, pids/mem/cpu limits, host uid:gid, labels for stale-reap; rejects env values with newlines.
• stale-reap.ts — reaps leaked containers and tmp dirs by host-pid label (timeout-bounded, best-effort).

Core wiring

• src/index.ts — --sandbox flag, SKVM_IN_SANDBOX re-entry guard, launcher dispatch, config-command/native-mode guards, clean error output.
• src/core/config.ts — getSandboxConfig / getDefaultSandboxMode, resolveRouteApiKey env fallback, native-mode-under-sandbox enforcement at the resolveAdapterConfigMode choke point.
• src/core/types.ts — SandboxConfigSchema (validated memory/cpus/network).
• src/providers/registry.ts — resolveRouteApiKey moved to core/config.ts (re-exported; behaviour preserved).
• src/cli-config/index.ts — config init/show/doctor surface the sandbox slice plus docker/image checks.

Image + docs

• docker/skvm-sandbox.Dockerfile — Ubuntu 24.04 + Bun + opencode + claude-code + baked skvm binary.
• README.md — --sandbox semantics, image build, cleanup recipes.

Adapter code (src/adapters/*.ts) is unchanged — the defining property.

Test plan

• bunx tsc --noEmit
• bun test — 1013 pass, 0 fail
• Manual e2e on a Linux host with Docker:

bun run build:binary
docker build -f docker/skvm-sandbox.Dockerfile -t ghcr.io/sjtu-ipads/skvm-sandbox:$(bun run skvm --version) .
# real run through the container — resolves route, injects key, calls the model:
skvm run --sandbox --task=task.json --model=cheap_ipads/gpt-4o-mini   # -> HELLO_SANDBOX
skvm run --sandbox config doctor      # hard-errors (config is host-only)
skvm run --sandbox --adapter-config=native ...   # hard-errors (managed-only)
skvm run --sandbox --debug-sandbox ...           # argv printed, keys <redacted>

Verified end-to-end: image build, in-container tooling, launcher roundtrip, a real LLM run with artifacts persisted back to the host cache, and all guard / redaction paths.

Notes for reviewers

• Security model: keys are stripped from the mounted config and injected via env (SKVM_ROUTE_<id>_KEY); the design accepts that env-readable keys remain visible to in-container code (network=bridge is required for LLM calls). --debug-sandbox redacts key values.
• src/index.ts global error handler now prints error: <msg> by default (full stack under --verbose/SKVM_DEBUG). This affects all commands, not just sandbox — happy to split it out if you'd prefer the PR stay strictly sandbox-scoped.
• Image footprint: the locally-built image is ~1.48 GB (Ubuntu 24.04 + apt curl/git/python3/nodejs/npm/jq/unzip + Bun + opencode binary + global @anthropic-ai/claude-code npm install + skvm binary). Reasonable for an agent sandbox but not lean. Multi-stage build, debian-slim base, and dropping the python3/npm/jq apt set are the obvious slimming levers — left as follow-ups so this PR stays scoped to the launcher mechanism.
• Deferred follow-ups (intentional, not blockers): pi/hermes/openclaw in the image (only bare-agent/opencode/claude-code today); release pipeline for multi-arch image push; --mount-extra colon-in-path limitation; stripping non-route host paths (adapters/headlessAgent) from the mounted config; baseUrl-embedded-credentials stripping; pinning Bun in the Dockerfile.
• This supersedes the earlier per-adapter direction; that branch is left unmerged as reference.

Checklist

• Linked an issue ([feature] Optional Docker sandbox for skvm runs (--sandbox) #30)
• Commit messages follow <scope>: <summary> style
• Added or updated tests where appropriate
• Updated README.md / docs/skvm/ where behaviour changed
• No unrelated changes mixed in — see the global-error-handler note above

[lec77]

Pushed follow-up commits addressing the review feedback:

• Path-list flags — --skill, --logs, --failures, --tasks, --test-tasks accept comma-separated lists. The launcher now splits these and resolves / mounts / rewrites each element independently instead of treating the whole value as one path. --tasks / --test-tasks leave bare task IDs untouched and rewrite only path-like elements.
• Config extra mounts — sandbox.docker.extraMounts now go through the same denylist as --mount-extra (Docker socket and host root rejected) before any mount is composed.
• --no-auto-probe — now propagates into the container; the opt-out is no longer dropped at the host boundary.
• rw mount ownership — the cache root and dynamic out-of-root output dirs are created host-side (owned by the invoking user) before docker run, so the daemon no longer creates them as root and locks the host-uid container out.
• Cache-root prefix precedence — root matching is now longest-prefix, so a cache nested under the workspace (e.g. --skvm-cache=./.skvm) resolves to /skvm-cache and reads through the sanitized config overlay rather than the raw config under /workspace.

Each fix ships with regression tests; tsc is clean and the suite passes.

On the intermittent runTasksForRound adapterPool concurrency bound test: it's a pre-existing timing-sensitive concurrency test and is independent of this change — the diff doesn't touch the jit-optimize / adapter-pool path, and it passes in isolation but flakes under full-suite parallelism. I'd suggest tracking it in a separate issue to make it deterministic rather than blocking this PR.