Skip to content

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.

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.

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.

Terminal window
appsec-sbx create appsec-sbx --provider openrouter
appsec-sbx verify appsec-sbx

Before 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:

Terminal window
appsec-sbx import appsec-sbx /absolute/path/to/your/git-checkout
appsec-sbx skills appsec-sbx https://github.com/aai-institute/agentic-appsec-playbook --subdir sandbox/skills
appsec-sbx shell --key appsec-sbx # paste the key at the prompt; you are now inside the VM

skills 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:

Terminal window
cd ~/target/source
opencode
# 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:

Terminal window
appsec-sbx export appsec-sbx ./findings.zip
appsec-sbx stop appsec-sbx

Choose 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.

  • 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.json and skills.json beside 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.

  • 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-create and destroy need the sbx daemon’s credential access, which a desktop logon provides. Clone the target with core.autocrlf=false if you want the import hashes to match a Linux or macOS checkout. Windows console: pass guest commands as plain words, or put a script and exec sh it.