Runbook: Setup & Sandbox (one-time per host)
Owner: Security engineer (sandbox operator) | Frequency: Once per host, or after a provider/region/allowlist change | Last Updated: 2026-08-14 | Last Run: —
Verified against ../../../samples/defending-code-reference-harness/
(scripts/setup_sandbox.sh, bin/vp-sandboxed, harness/auth.py).
Purpose
Get a host ready to run the autonomous pipelines (vuln-pipeline, dnr-pipeline) safely:
gVisor registered as a Docker runtime, the egress-restricted vp-internal network and
allowlist proxy running, and credentials resolvable. bin/vp-sandboxed refuses to launch
either pipeline until this is done.
Prerequisites
- [ ] Linux host (x86_64 or aarch64) with Docker installed and
sudoaccess — gVisor needs a real Linux kernel; on macOS/Windows, run inside a Linux VM - [ ]
python3 -m venvavailable (Python ≥3.11 perpyproject.toml) - [ ] Model credentials ready:
ANTHROPIC_API_KEY, orCLAUDE_CODE_OAUTH_TOKEN, or a Bedrock/Vertex identity (see Step 3) - [ ] If using a non-default
ANTHROPIC_BASE_URL, Bedrock, or Vertex: know the exact egress host(s) you'll need (Step 2'sVP_EGRESS_ALLOW)
Procedure
Step 1: Install the Python package
cd samples/defending-code-reference-harness
python3 -m venv .venv && .venv/bin/pip install -e .
Expected result: .venv/bin/vuln-pipeline and .venv/bin/dnr-pipeline entry points
exist (bin/vp-sandboxed checks for these before doing anything else).
If it fails: Python <3.11 — check python3 --version; pyproject.toml requires
>=3.11.
Step 2: Run the sandbox setup script
./scripts/setup_sandbox.sh
Set VP_EGRESS_ALLOW=host-1:443,host-2:443 before this command if you're on a
non-default ANTHROPIC_BASE_URL — the variable replaces the default allowlist rather
than extending it, so include every host the agents need. For Bedrock, the allowlist is
auto-derived from AWS_REGION; for Vertex it is not auto-derived — set it explicitly (see
Step 3).
Expected result: Script prints == gVisor (runsc) ==, == ... network ==,
== ... images ==, == ... checks == sections, each ending ok. The final allow: line
reports the egress list the proxy actually loaded — check it matches what you expect.
If it fails: Needs sudo (installs a runtime, edits /etc/docker/daemon.json) — run
with sudo access available. On rootless/nested Docker, the script detects that runsc can't
manage cgroups and re-registers with --ignore-cgroups automatically; isolation is
unaffected, only per-container memory caps aren't enforced.
Step 3: Set model credentials
Pick one:
# Direct API
export ANTHROPIC_API_KEY=sk-ant-...
# Claude Code OAuth
export CLAUDE_CODE_OAUTH_TOKEN=...
# Bedrock (set BEFORE step 2, so the allowlist auto-derives correctly)
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK=... # preferred over access keys — no IAM lateral-movement risk
# Vertex (egress NOT auto-derived — set VP_EGRESS_ALLOW before step 2)
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=...
export CLOUD_ML_REGION=...
Expected result: none visible yet — verified in Step 4.
If it fails: On Bedrock, a bare foundation-model id (starting anthropic.) fails on
first call with ValidationException: ... on-demand throughput isn't supported. Use the
cross-region inference-profile prefix matching your deployment's region group (us.,
eu., apac., global.) — e.g. Korea (ap-northeast-2) needs apac.anthropic...., not
us.anthropic.....
Step 4: Verify isolation
docker run --rm --runtime=runsc vuln-pipeline-canary-latest-agent:latest uname -r
uname -r
# expect two DIFFERENT kernel versions
Expected result: The two commands print different kernel versions, confirming gVisor
is actually in use (not just installed).
If it fails: setup_sandbox.sh didn't complete — re-run it and check for fail lines.
Verification
- [ ]
bin/vp-sandboxed run canary --model <model-id> --runs 1launches without the "runtime not registered" or "proxy not running" errors - [ ] The four verification commands in
docs/agent-sandbox.mdall pass (kernel version differs, host file read fails inside the container, model API reachable, other hosts refused)
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
error: runtime 'runsc' not registered |
Setup script didn't complete, or ran on a host without gVisor support | Re-run scripts/setup_sandbox.sh; confirm Linux x86_64/aarch64 |
error: vp-egress-proxy not running on vp-internal |
Proxy container isn't up (crashed, or setup was interrupted) | Re-run scripts/setup_sandbox.sh; check docker ps for vp-egress-proxy |
Preflight check_egress_satisfied fails |
Provider env (Bedrock/Vertex/base-URL) changed after the proxy was built, so its allowlist is stale | Re-run scripts/setup_sandbox.sh with the current provider env set — this drops any live agent connections, so do it between batches, not during one |
ValidationException on first Bedrock call |
Bare foundation-model id instead of a region-prefixed inference profile | Use us./eu./apac./global.anthropic.... matching your deployment region |
Rollback
No destructive state to roll back — setup_sandbox.sh is idempotent and safe to re-run.
To fully remove: docker network rm vp-internal, docker rm -f vp-egress-proxy, remove
/usr/local/bin/runsc and the runsc entry from /etc/docker/daemon.json.
Escalation
| Situation | Contact | Method |
|---|---|---|
Need sudo/host access you don't have |
Infra/platform team | Standard access-request channel |
| Bedrock/Vertex credential scoping questions | Cloud security team | Standard access-request channel |
| gVisor incompatible with a required host config (e.g. nested virtualization edge cases) | Security engineering lead | Escalate before falling back to --dangerously-no-sandbox — that flag is for throwaway-VM development only |
History
| Date | Run By | Notes |
|---|---|---|
| — | — | — |