Research: Docker Sandboxes (sbx) as opt-in process isolation

[samkeen]

Why

Today Tilth's only worker containment is cwd=workspace for the bash tool (tilth/tools/bash.py) plus a narrow denylist in pre_tool (force-push, sudo, curl|sh). _resolve keeps the file tools well-behaved, but bash runs with the full credentials of the user running uv run tilth — cat /etc/passwd, cat ../../.env, cat ../../sessions/<id>/events.jsonl all succeed. See discussion in #10.

This issue is the research artifact for an opt-in isolated mode: a secondary mode that wraps the harness in real process isolation. Default mode stays best-effort. No code changes proposed here.

Design preference (settled)

When isolated mode is requested for a session, pick the most-isolated option that's actually available on the host, in this order:

1. Apple Containerization (container CLI) — if Apple Silicon + macOS 26+ + container installed and container system start'd. Apache-2.0, sub-second microVM, native fit. Preferred when available.
2. Docker Sandboxes (sbx) — if sbx is installed and authenticated. Cross-platform fallback covering Intel Macs, Linux (KVM required), Windows.
3. Default best-effort — what Tilth does today. Always available.

Default mode stays best-effort; isolated mode is opt-in (default behaviour unchanged for users who don't ask for it).

CLI shape deferred to a future implementation issue: probably --sandbox with auto-detect-and-announce (verbose log line saying which backend got picked), with explicit --sandbox=apple|sbx available as an override.

Integration shape

Two integration levels, with strong preference for the first regardless of backend:

1. Wrap-the-harness (recommended). The whole uv run tilth ~/projects/foo process runs inside the sandbox. Workspace + sessions/ are bind/passthrough mounted so --resume and --visualize from the host still see the same session dir. Likely zero-code, possibly one thin CLI affordance per backend.
2. Wrap-the-tool-calls (not recommended). Harness on host, each bash tool call routed through sandbox exec. Invasive — every tool needs sandbox awareness, file tools too. Loses the simplicity of "the worker is one process in a known cwd."

(1) is the natural fit given Tilth's process model.

Backend: Apple Containerization (container)

• License: Apache-2.0. Source at github.com/apple/container.
• Platform: Apple Silicon only. Requires macOS 26 (Tahoe) for full functionality; less capable on macOS 15.
• Tech: one lightweight Linux microVM per container (not a shared-kernel Docker model). Swift-based vminitd per VM. Sub-second cold start.
• Image format: fully OCI-compatible. Any standard image from a standard registry works. Run a tilth-sandbox image (preinstalled uv + Python) the same way you'd run any OCI image.
• Maturity: pre-1.0, active development, breaking changes possible between minor versions.
• Tilth fit: when available, this is the right choice — open source, native, fast, no Docker Inc. dependency.

Backend: Docker Sandboxes (sbx)

What it is

• microVM-per-sandbox (not a container). Linux uses KVM (sudo usermod -aG kvm $USER); macOS uses the platform hypervisor (Apple Virtualization Framework, not explicit in docs); Windows uses Hyper-V.
• Released GA, v0.30.0 (May 2026) — sub-1.0, expect churn.
• Proprietary (Docker Inc.). github.com/docker/sbx-releases ships binaries only. Free for core functionality; team admin controls (network restrictions, FS policies) require sales engagement.
• Docker Desktop not required.
• Pitched specifically at coding-agent workloads. Recognised agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell.

Sources: product page, docs, usage, get started, architecture.

How isolation works

• Filesystem: workspace mounted via passthrough; absolute paths preserved between host and sandbox. Multiple workspaces via sbx run/create AGENT PATH [PATH...], with :ro suffix for read-only.
• Network: all egress routed through an HTTP/HTTPS proxy on the host. Default-deny with three policy presets at first sbx login; docs recommend Balanced. Allowlist additions via sbx policy allow network -g <host:port>. sbx policy also has named profiles for team governance.
• Secrets: sbx secret set -g <service> stores in the OS keychain (service names like github, anthropic, openai); the host proxy injects into outbound API requests so the secret never appears inside the sandbox. Alternative: sbx exec -e KEY=VAL passes env vars directly, identical to docker exec.
• Lifecycle: sbx create → sbx run (attach) → sbx stop (env persists) → sbx rm (destroy). sbx exec -it <name> bash to drop into an existing sandbox.
• Resource limits: --cpus, -m/--memory (defaults to 50% host, max 32 GiB).
• Custom base image: -t/--template <oci image> — agent-specific image by default, but a custom OCI image is supported. We could ship tilth-sandbox preinstalled with uv + Python.
• Other utilities: sbx cp (file copy host↔sandbox), sbx ports (publish sandbox ports), sbx diagnose (debug install).
• Surprise overlap: sbx run --branch creates a git worktree as part of the sandbox. Overlaps directly with Tilth's worktree machinery — if Tilth runs inside sbx, we'd ignore the flag and let Tilth manage its own worktrees as today.

Automation-friendly invocation

For a --sandbox mode driven from a script:

sbx create shell . --name tilth-session-<id> [--memory 8g --cpus 4]
sbx exec -e TILTH_API_KEY="$TILTH_API_KEY" \
         -e TILTH_MODEL="$TILTH_MODEL" \
         -w /workspace tilth-session-<id> \
         uv run tilth ~/projects/tilth-demo
sbx rm tilth-session-<id>   # or keep for resume

Frictions specific to sbx

• Proprietary — strategic dependency on a closed Docker Inc. product. Bounded since this is an opt-in second backend.
• Linux requires KVM — rules out most cloud VMs without nested virt and most CI runners. Dev-machine use on macOS / Windows / Linux desktop is the realistic target.
• Sub-1.0 maturity — CLI surface may churn.

Other options considered

• sandbox-exec — built into macOS (no install), kernel-level sandbox profiles (Scheme/LISP syntax), zero VM overhead. Apple has technically deprecated it for app distribution but it remains the lowest-friction macOS option for sandboxing arbitrary CLI tools. There's an open issue against apple/container asking Apple to clarify the deprecation timeline. Profile authoring is painful. Could become a fourth-tier fallback for Intel Macs if we want to avoid the sbx dependency there; not pursuing in the first cut.
• Plain Docker / rootless podman — weaker isolation (shared kernel), but ubiquitous on Linux. Could be a Linux-only fallback ahead of sbx in the preference order if we want to keep all backends open source. Not pursuing in the first cut.

Comparison matrix

Backend	OS support	License	Maturity	Isolation	Overhead
Apple container	Apple Silicon + macOS 26+ only	Apache-2.0	pre-1.0	microVM per container	sub-second
Docker sbx	Mac / Win / Linux	Proprietary	v0.30	microVM	VM boot
sandbox-exec	macOS only	Built-in	Stable but discouraged	Kernel profile	negligible
Plain Docker / rootless podman	All / Linux	OSS	Stable	Shared kernel / namespaces	Low

Open questions (verify by running)

• Default network policy on Balanced: does it include OpenRouter (openrouter.ai)? OpenAI, Anthropic, Google almost certainly yes.
• Does localhost:11434 from inside a sbx microVM reach the host's Ollama, or does it need a bridge (host.docker.internal-style)?
• Same network + filesystem questions for Apple container, plus its default network policy.
• Cold microVM boot time on Mac (sbx, Apple container) and Linux (sbx + KVM).
• License terms for sbx — anything restricting commercial use of the runtime itself.

Proposed next step

Install both sbx (already done) and Apple container on a dev machine, run the demo inside each (sbx run shell → uv run tilth ~/projects/tilth-demo, equivalent for container), document what breaks. Cheap probes that answer most of the open questions and confirm whether wrap-the-harness is genuinely zero-code per backend or wants a thin --sandbox affordance.

[samkeen]

Update: ran sbx --help locally + researched the macOS-native alternatives

sbx open questions, resolved

1. sbx run is restricted to named agents (claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell). Critical: shell is one of them — sbx run shell . drops you into a shell sandbox in cwd, which is the escape hatch for running arbitrary commands like uv run tilth.
2. sbx exec is exactly docker exec-shaped: -e/--env, --env-file, -i/-t, -w/--workdir, -u/--user, -d/--detach. So env vars can be passed in explicitly (-e TILTH_API_KEY=...) — the keychain isn't the only path. Closes the secret-handling question.
3. Workspace mounting: sbx run/create <agent> <path> [<path>:ro ...] — multiple workspaces, :ro suffix for read-only.
4. Resource limits: --cpus, -m/--memory (defaults to 50% host, max 32 GiB).
5. Custom base image: -t/--template <oci image> — agent-specific image by default, but a custom OCI image is supported. This is a big deal — we could ship a tilth-sandbox image preinstalled with uv + Python.
6. sbx cp copies files host↔sandbox (so passthrough-mounting everything isn't required).
7. sbx ports publishes sandbox ports to host (loopback by default).
8. sbx policy has a profile subcommand for named governance profiles applied via run --profile. Team-scale governance hook.
9. sbx secret is per-service-name (github, anthropic, openai) and proxy-injected into outbound API requests. Useful for the big providers; doesn't auto-cover arbitrary endpoints like OpenRouter, but -e to sbx exec covers those.
10. Surprise: sbx run/create has a --branch flag that creates a git worktree on a named branch as part of the sandbox. Overlaps directly with Tilth's worktree machinery — if Tilth runs inside sbx, we'd ignore sbx's branch flag and let Tilth manage its own worktrees as today.

Most automation-friendly invocation shape

For a --sandbox mode driven from a script:

sbx create shell . --name tilth-session-<id> [--memory 8g --cpus 4]
sbx exec -e TILTH_API_KEY=\"$TILTH_API_KEY\" \\
         -e TILTH_MODEL=\"$TILTH_MODEL\" \\
         -w /workspace tilth-session-<id> \\
         uv run tilth ~/projects/tilth-demo
sbx rm tilth-session-<id>   # or keep for resume

macOS-native alternatives worth weighing

sbx is the cross-platform answer but it's proprietary and Linux needs KVM. Two macOS-native options change the picture for Mac users:

Apple Containerization framework + container CLI — released at WWDC 2025, Apache-2.0, Apple Silicon only, requires macOS 26 (Tahoe), pre-1.0. Runs OCI-compatible images as lightweight Linux microVMs (one VM per container, sub-second cold start). For Tilth: pull/build an OCI image with uv + Python, container run -v ~/projects/tilth-demo:/workspace tilth-sandbox uv run tilth /workspace. Better fit than sbx for Apple Silicon developers: open source, faster, no Docker Inc. dependency. Downside: doesn't help Intel Macs, doesn't help Linux/Windows, pre-1.0 churn risk.

sandbox-exec — built into macOS (no install), kernel-level sandbox profiles (Scheme/LISP syntax), zero VM overhead. Apple has technically deprecated it for app distribution but it remains the lowest-friction macOS option for sandboxing arbitrary CLI tools. There's an open issue against apple/containerization asking Apple to clarify the deprecation timeline and provide a replacement — so its future is uncertain. Profile authoring is painful but well-understood; reference profiles exist for tools like Chromium.

Revised option matrix

Option	OS support	License	Maturity	Isolation	Overhead	Notes
sbx	Mac/Win/Linux	Proprietary	v0.30	microVM	VM boot	Best cross-platform; Linux needs KVM
Apple container	Apple Silicon + macOS 26+ only	Apache-2.0	pre-1.0	microVM per container	sub-second	OCI-compatible; best fit for AS Mac users
sandbox-exec	macOS only	Built-in	Stable but discouraged	Kernel profile	negligible	Profile authoring is painful; uncertain future
Plain Docker container	All (Docker req'd)	OSS	Stable	Shared kernel	Low	Weakest isolation but most ubiquitous
Linux rootless podman / bwrap / nspawn	Linux only	OSS	Stable	Namespaces	Low	Solid for Linux-only deployments

Suggested direction

If "don't require Docker" is the constraint, the cleanest positioning is probably:

• macOS (Apple Silicon, Tahoe+) — Apple container wrapper with a maintained tilth-sandbox OCI image. Open source, fast, native.
• macOS (Intel or pre-Tahoe) — sbx (proprietary but works) or sandbox-exec (research effort).
• Linux — rootless podman with the same OCI image, or sbx if user opts in.
• Windows — sbx is the realistic option.

That's three integrations to maintain. Pragmatic first cut: pick one (probably sbx for breadth) and document the others as future options.

Open questions remaining (still need verification by actually running)

• Default network policy: is OpenRouter (openrouter.ai) reachable on "Balanced"?
• Does localhost:11434 from inside a sbx microVM reach the host's Ollama, or does it need a bridge (host.docker.internal-style)?
• Cold microVM boot time on Mac (sbx) and Linux (sbx + KVM).
• Apple container: same network + filesystem questions, plus what its default policy looks like.

[samkeen]

Design preference (settled)

When "isolated mode" is requested for a session, pick the most-isolated option that's actually available on the host, in this order:

1. Apple Containerization (container CLI) — if Apple Silicon + macOS 26+ + container installed and container system start'd. Apache-2.0, sub-second microVM, native fit. Preferred when available.
2. Docker Sandboxes (sbx) — if sbx is installed and logged in. Cross-platform fallback covering Intel Macs, Linux (KVM required), Windows.
3. Default best-effort — what Tilth does today: cwd=workspace for bash, narrow pre_tool denylist, no process isolation. Always available.

Default mode stays best-effort; isolated mode is opt-in (default behaviour unchanged for users who don't ask for it).

Implementation question deferred to a future issue: whether the CLI is --sandbox (auto-detect best available, log which was picked) or explicit --sandbox=apple|sbx. Leaning auto-detect with a verbose announce so users aren't surprised which backend got selected.