Direct API

docs / process / runbooks / setup-and-sandbox

← all docs

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

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

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
— — —