feat(agent): add Docker sandbox backend for agent run

.gitignore

@@ -2,4 +2,5 @@
 .env
 .env.*
 .stashbase/*
-.serena/*
+.serena/*
+docs/superpowers/

README.md

@@ -13,6 +13,7 @@ Stashbase is an open-source access layer that gives coding agents the access the
   - [How the Agent Proxy Works](#how-the-agent-proxy-works)
   - [Profile Syntax and Configuration](#profile-syntax-and-configuration)
   - [Filesystem and Network Containment](#filesystem-and-network-containment)
+  - [Docker Sandbox Backend](#docker-sandbox-backend)
   - [Remote Agent Sessions](#remote-agent-sessions)
   - [MCP Tools Authorization](#mcp-tools-authorization)
   - [Audit Logs and Session Revocation](#audit-logs-and-session-revocation)
@@ -231,7 +232,7 @@ deny_write = [".git", "~/.ssh", "~/.aws"]
 
 On macOS, Stashbase wraps the agent in Seatbelt, which enforces filesystem rules. On Linux and WSL2, it uses `systemd-run --user` with cgroup IP rules, or falls back to `bubblewrap` for namespace isolation. Windows native is not implemented; use WSL2 instead.
 
-Denied reads return `/dev/null`; denied writes go to an empty overlay. Existing file descriptors and data already in memory are not affected. These are policy-only; these profiles do not require secrets.
+Denied reads see empty content (a genuine empty regular file, not `/dev/null` — that's a character device, which confuses tooling that expects a normal file at that path); denied writes go to an empty overlay. Existing file descriptors and data already in memory are not affected. These are policy-only; these profiles do not require secrets.
 
 #### Network containment
 
@@ -241,6 +242,27 @@ On macOS, this uses the deprecated `sandbox-exec` utility. On Linux and WSL2, it
 
 This is network containment only, not filesystem, process-memory, or kernel isolation.
 
+**If Docker is available, prefer the Docker sandbox backend below over the native one** — it's meaningfully stronger: filesystem access is allow-list rather than deny-list (nothing outside the working directory is visible at all, instead of specific paths being blocked), network egress is enforced at the network layer rather than relying on the agent to honor its proxy environment variables, and it works identically across macOS, Linux, and Windows (via Docker Desktop) instead of needing platform-specific mechanisms with a Windows gap. The native backend remains the default for now since it needs nothing beyond the CLI itself, but Docker is the recommended choice whenever it's an option.
+
+### Docker Sandbox Backend
+
+The recommended backend when Docker is available: the agent runs inside a Docker container instead of a same-host sandboxed process, with allow-list filesystem access and a network-layer firewall (enforced even against an agent that deliberately ignores its proxy env vars).
+
+```toml
+[sandbox]
+backend = "docker"
+```
+
+```bash
+stashbase agent run --profile coding -- claude
+```
+
+Or override the profile's choice for one invocation without editing the file: `--docker-sandbox true|false`, per-run image overrides with `--docker-image <ref>` / `--docker-dockerfile <path>`, and resource caps with `--docker-memory <value>` / `--docker-cpus <value>` (also settable per profile via `[sandbox] memory`/`cpus`; no cap by default).
+
+Claude Code and Codex are pre-installed in the default sandbox image; a profile can also run its own image or Dockerfile instead (`[sandbox] image`/`dockerfile`) to add other tools, without loosening any of the sandbox constraints themselves.
+
+See **[docs/sandboxing.md](docs/sandboxing.md)** for the full picture: how the network firewall is enforced, custom images, git identity forwarding, login persistence across images, Codex/Claude Code OAuth quirks, and current limitations.
+
 ### Remote Agent Sessions
 
 Use `--remote` to run with credentials managed entirely in the Stashbase control plane. Profiles can use either application secrets with `[secrets]` (requires `project` and `environment`) or user-specific `[personal_credentials]` (no Stashbase API key required):

docker/agent-sandbox/Dockerfile

@@ -0,0 +1,78 @@
+# Node.js is still needed here even though Claude Code and Codex are
+# installed as native binaries below (neither invokes Node itself at
+# runtime): MCP servers agents commonly connect to are typically run via
+# `npx`, so `npm`/`node` need to be on PATH for those to work. This is a
+# Debian base underneath (bookworm-slim variant), so apt-get below works
+# the same as it would on `debian:bookworm-slim`.
+FROM node:22-bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        gh \
+        bubblewrap \
+        iptables \
+        jq \
+        dnsutils \
+        unzip \
+        less \
+        procps \
+        python3 \
+        python3-pip \
+        python3-venv \
+    && rm -rf /var/lib/apt/lists/*
+
+# Debian's system pip refuses a bare `pip install` (PEP 668,
+# "externally-managed-environment") to protect the OS's own Python install
+# from being clobbered by unrelated packages. That protection matters far
+# less for an ephemeral sandbox container than it does on a real host — the
+# base image itself is never mutated at runtime, so there's nothing lasting
+# to corrupt — so it's relaxed here for a working `pip install` out of the
+# box. `python3-venv` is still included for anyone who wants an isolated
+# environment anyway.
+ENV PIP_BREAK_SYSTEM_PACKAGES=1
+
+# Claude Code and Codex are installed via their own official native
+# installers rather than `npm install -g` — both projects document this as
+# the recommended method: it installs a self-contained platform binary
+# (no Node runtime involved for the tool itself, unlike the npm package
+# which just wraps the same binary), and pulls from Anthropic's/OpenAI's
+# own signed release infrastructure rather than the npm registry.
+#
+# Both installers default to installing under $HOME (`/root` during this
+# build) and only add `~/.local/bin` to *root's* shell profile — neither
+# knows this container will later run as an arbitrary uid (see the --user
+# flag set on Linux in docker_run_command). So: make the installed trees
+# world-readable/executable (`chmod -R a+rX`, never +w — nothing here
+# should be writable by the sandboxed process) and symlink both into
+# `/usr/local/bin`, which is on PATH for every user by default. Verified
+# directly that both `claude --version` and `codex --version` work when
+# invoked as a non-root uid with this layout, not just as root.
+#
+# Codex ships helper binaries (a code-mode host, voice tools) alongside
+# its main executable, so its install tree is kept intact and symlinked
+# rather than copying a single binary out the way Claude Code's simpler,
+# single-file layout would allow.
+RUN curl -fsSL https://claude.ai/install.sh | bash \
+    && curl -fsSL https://chatgpt.com/codex/install.sh | sh \
+    && chmod 755 /root \
+    && chmod -R a+rX /root/.local /root/.codex \
+    && ln -s /root/.local/bin/claude /usr/local/bin/claude \
+    && ln -s /root/.local/bin/codex /usr/local/bin/codex
+
+# A persistent volume is mounted here (see docker_sandbox.rs) so login
+# state (e.g. Claude Code's ~/.claude, ~/.claude.json) survives across
+# runs instead of vanishing with each --rm'd container. World-writable
+# because the container may run as an arbitrary host uid (see the --user
+# flag set on Linux in docker_run_command) with no matching passwd entry,
+# so a named volume freshly created by Docker would otherwise be
+# root-owned and unwritable to that uid.
+RUN mkdir -p /home/agent && chmod 777 /home/agent
+
+# `iptables` above is used by the short-lived network-namespace-holder
+# container (see start_netns_holder in docker_sandbox.rs), which uses this
+# same image — the actual agent container never runs iptables itself and
+# holds no networking capabilities at all.
+WORKDIR /workspace

docs/agent-profiles.md

@@ -53,7 +53,7 @@ paths = ["/user", "/repos/*"]
 
 The child process receives `GH_TOKEN` as a placeholder. When it makes a matching HTTP request (GET to `/user` or `/repos/*` on `api.github.com`), the proxy injects the real token. Any unmatched request is blocked.
 
-## Filesystem and Network Restrictions
+## Filesystem, Network Restrictions, and Sandbox Backends
 
 Restrict what the child can read or write:
 
@@ -63,12 +63,11 @@ deny_read = ["~/.ssh", "~/.aws"]
 deny_write = ["~/.git"]
 ```
 
-Paths use explicit prefixes: `~` for home, relative paths for the current directory. Enforcement uses platform-native mechanisms:
-- **macOS**: Seatbelt sandbox
-- **Linux**: `systemd-run` or `bubblewrap` (automatic fallback)
-- **Unsupported platforms**: Validation fails closed; the run does not proceed
+Paths use explicit prefixes: `~` for home, relative paths for the current directory.
 
-Existing file descriptors and data already in process memory remain unrestricted.
+By default, enforcement uses the platform-native mechanism (Seatbelt on macOS, `systemd-run`/`bubblewrap` on Linux). **If Docker is available, prefer `[sandbox] backend = "docker"` instead** — it's meaningfully stronger (allow-list filesystem access, a real network-layer firewall, and it works on Windows too, unlike the native backend).
+
+See **[Sandboxing](sandboxing.md)** for the full picture: both backends, how the Docker backend's network firewall is enforced, custom images, git identity forwarding, login persistence, and Codex/Claude Code OAuth quirks.
 
 ## Network Access and HTTP Rules
 
@@ -205,7 +204,7 @@ The proxy is HTTP/HTTPS only and designed for standard developer tools. It does
 - Request-body or query-parameter injection (credentials are header-only)
 - Process-level isolation (same-user processes can still access broader system credentials)
 
-For complete network isolation, use a container or VM.
+For stronger filesystem and network isolation than the native backend provides, see [Sandboxing](sandboxing.md).
 
 ## Full Reference
 

docs/agent-profiles/integrations.md

@@ -8,7 +8,7 @@ Claude Code can access external tools and APIs through agent profiles. For examp
 
 ```toml
 # .stashbase/agents/claude.toml
-egress_hosts = ["api.anthropic.com", "mcp.linear.app"]
+egress_hosts = ["api.anthropic.com", "platform.claude.com", "mcp.linear.app"]
 
 [secrets]
 project = "my-project"
@@ -37,13 +37,15 @@ stashbase agent run --profile claude -- claude
 
 Claude Code receives only the Linear credential placeholder and can use allowed MCP tools through the proxy.
 
+`platform.claude.com` is required alongside `api.anthropic.com` if you're logged in via OAuth (`/login` in Claude Code) rather than an API key — Claude Code's OAuth login and silent token refresh both go through `platform.claude.com`, a different host than the one used for actual model requests. Without it, login itself fails with "OAuth error: proxy refused the connection", or — if you were already logged in before restricting egress — the session works until the access token's next refresh is silently blocked, then fails hours later with "OAuth access token has expired."
+
 ## Codex
 
 Codex needs GitHub access for repository operations and OpenAI for completions:
 
 ```toml
 # .stashbase/agents/codex.toml
-egress_hosts = ["api.openai.com", "chatgpt.com", "api.github.com"]
+egress_hosts = ["api.openai.com", "chatgpt.com", "auth.openai.com", "api.github.com"]
 allow_hooks = ["dependency_check"]
 
 [secrets]
@@ -81,6 +83,8 @@ Run:
 stashbase agent run --profile codex -- codex
 ```
 
+`auth.openai.com` is required for `codex login --device-auth` (and its silent token refresh) — it's a different host than `api.openai.com`, which only serves completions. Without it, device-code login fails with an error like "failed to request device code: error sending request for url (https://auth.openai.com/api/accounts/deviceauth/usercode)".
+
 ## HTTP MCP Server
 
 MCP servers over HTTP (like Linear) use a separate credential binding and tool allowlist: