appsec-sbx: run agents in a sandbox
appsec-sbx manages a Docker Sandboxes (sbx) virtual machine with one model
provider and a copy of your repository inside. The VM runs one agent harness,
the program that connects the model to files and commands, such as OpenCode.
The harness and the programs it starts are called the workload.
From your machine, the wrapper creates the VM and installs its tools, restricts network access to the provider and selected registries, imports source files, installs review skills and supplies the model credential. It exports results as an archive without extracting it on the host. Before entry, it checks for shared host folders and ports exposed outside the VM. DNS isolation remains a validation gap; allowed hostnames that resolve to private addresses are refused on sbx 0.49.1 and later.
It supports the no-regret measures on sbx. You remain responsible for checking source for secrets, approving provider access, managing credentials and budgets, testing the kill switch and resetting between independent reviews. Allowed services can still receive data the agent can read; see the remaining risks.
Before the first run
Section titled “Before the first run”Complete Getting started, steps 2–4
once per host: install and log in to sbx, initialise a fresh global policy with
deny-all, disable SSH agent forwarding, restart the daemon and run its
diagnostics. Then install the wrapper and prepare a model credential with a
budget. The review skill is fetched directly from GitHub during the run setup.
The commands below assume appsec-sbx is on your PATH. See
Install the wrapper for the uv
installation command and checkout-based alternatives on each platform.
Supported hosts: macOS on Apple silicon, Windows 11 x64 and Linux x86_64, each with a working
sbx installation and Python 3.10 or newer. uv tool install fetches a suitable Python if the
host has none; the python3 that ships with macOS is 3.9 and too old. The wrapper refuses sbx releases before 0.45.0, which also rules out the
macOS guest-to-host escapes Docker
fixed in 0.42.0 (CVE-2026-77179,
CVE-2026-79994). Keep sbx current; its release notes are at
docker/sbx-releases. On other hosts the wrapper prints an untested-host note and continues.
Platform specifics are at the end of this page.
Run a review
Section titled “Run a review”This is the same OpenRouter API-key workflow as Getting started. For another provider or a subscription login, follow Providers and credentials. Run these commands on the host for a new VM. For an existing VM, follow Starting another review.
The import source can also be a public GitHub repository URL, with optional
--ref <branch, tag or commit> (default: main). See
Import and export.
appsec-sbx create appsec-sbx --provider openrouterappsec-sbx verify appsec-sbxBefore adding a credential, complete the network denial checks. Then, before importing code or starting an agent, complete the kill-switch rehearsal. It tests stopping a running command, revoking the credential at the provider and restoring the clean VM. Then continue on the host:
appsec-sbx import appsec-sbx /absolute/path/to/your/git-checkoutappsec-sbx skills appsec-sbx https://github.com/aai-institute/agentic-appsec-playbook --subdir sandbox/skillsappsec-sbx shell --key appsec-sbx # paste the key at the prompt; you are now inside the VMskills fetches main into a temporary host checkout. Add --ref <commit>
to repeat a reviewed revision; see Review skills.
shell --key stores the API key on the host and enters in one step. The key
never enters the VM: the workload sees a placeholder, and sbx’s proxy adds the
key to requests to the provider. The stored key stays until unkey, stop,
reset or destroy, so a plain shell is enough when you return to the same review.
Inside the VM you are the unprivileged appsec user. Start OpenCode:
cd ~/target/sourceopencode# pick a model, then ask: "Use the security-review-repo skill to review this repository."The skill writes its report to ~/out/findings.md. Leave the harness, exit the
shell, and from the host:
appsec-sbx export appsec-sbx ./findings.zipappsec-sbx stop appsec-sbxChoose a new archive filename for each run; export refuses to overwrite an
existing file. Use .zip for ZIP or .tar.gz for gzip-compressed tar.
On Windows, inspect the ZIP with File Explorer and extract into a new, empty
directory. Read the report as untrusted text and keep it for later triage;
findings still need human review before you act on them. See
export formats.
stop is the kill switch: it stops the VM and its reproducers, removes the
stored key and attempts login-file cleanup while the VM is running. For subscription logins, run
appsec-sbx unkey appsec-sbx before stop to remove known login files
explicitly. Revoke or rotate credentials at the provider separately; see
credential cleanup limits.
Reset before every independent review, including another pass on the same
target. Export first, stop and revoke the old credential, then run reset
and verify, import the target and reinstall the skills. Supply a fresh
credential with a budget. import --replace only swaps source files and
retains other state. See
reset and reproducers
for the distinction between resuming a review and starting a new one.
On these pages
Section titled “On these pages”- Providers and credentials: the
createpresets, API keys, Claude Code and Codex seats, what to expect in the policy log. - VM lifetime, reset and policy: the idle stop and what it does to
credentials, reproducer VMs,
resetanddestroy, the global sbx policy the wrapper needs. - Skill installation: command syntax, file selection and pack updates.
- Import, export and host state: what goes in, what comes out, where the manifests live.
- Command reference: usage and options for every action.
Evidence after a run
Section titled “Evidence after a run”appsec-sbx logs <vm>prints the recent policy log: allowed and denied connections with timestamps. Denied bursts name what the harness or the agent tried to reach.import.jsonandskills.jsonbeside host state record what went in, with SHA-256 per file.- The export archive is the only thing that comes out.
Record the run with the discovery run report: provider, model, runtime, spend, denied hosts and what the report contained.
Platform notes
Section titled “Platform notes”- macOS (Apple silicon): nested gVisor does not work in the arm64 guest, which is why reproducers are separate VMs rather than containers. No user-visible difference.
- Windows 11: run the wrapper from a desktop session (Windows Terminal or PowerShell);
create,reset,repro-createanddestroyneed the sbx daemon’s credential access, which a desktop logon provides. Clone the target withcore.autocrlf=falseif you want the import hashes to match a Linux or macOS checkout. Windows console: pass guest commands as plain words, orputa script andexec shit.