Command reference
Use appsec-sbx --help to list commands and appsec-sbx ACTION --help for
help with one command. Every action takes the sandbox name as its first
argument and defaults to appsec-sbx. From a checkout,
./sandbox/make-appsec-sbx.sh and python -m appsec_sbx take the same arguments.
usage: appsec-sbx [-h] [--version] ACTION ...
appsec-sbx runs agents in Docker Sandboxes (sbx): a microVM with oneagent harness, one model provider and a filtered copy of your repository. Every actiontakes the sandbox name as its first argument (default: appsec-sbx).
Before the first review, create a VM and test stop and provider-side credentialrevocation. Start each independent review from a new VM or a clean reset: verify -> import -> skills -> shell --key -> (review inside) -> export -> stopRevoke the review credential at the provider afterwards.
positional arguments: ACTION create provision a clean workload VM with exactly one model provider verify run the entry guards and print guest versions import import a local checkout or public GitHub repository into ~/target/source skills install a skill pack from a local checkout or public GitHub URL key store the provider key for this VM on the host (prompted, never on the command line) unkey remove the stored key and the harness login stores exec run one command in the VM as the workload user shell interactive shell in the VM as the unprivileged workload user agent alias of shell export save ~/out as ZIP or tar.gz on the host (never extracted) put copy one host file to a new path under /home/appsec logs print the recent policy log (allowed and denied connections) status print sbx's description of the VM (sbx inspect) stop kill switch: remove the credentials, stop the VM and its reproducers repro-create create an offline reproducer VM from this primary's clean template reset DELETE the VM's current state and recreate it from the clean template destroy remove the VM and its reproducers entirely admin root maintenance shell (outside the workload boundary)
options: -h, --help show this help message and exit --version show program's version number and exit
`appsec-sbx ACTION --help` describes one action. Documentation:https://github.com/aai-institute/agentic-appsec-playbook (docs/)Actions
Section titled “Actions”| Action | Purpose |
|---|---|
create |
provision a clean workload VM with exactly one model provider |
verify |
run the entry guards and print guest versions |
import |
import a local checkout or public GitHub repository into ~/target/source |
skills |
install a skill pack from a local checkout or public GitHub URL |
key |
store the provider key for this VM on the host (prompted, never on the command line) |
unkey |
remove the stored key and the harness login stores |
exec |
run one command in the VM as the workload user |
shell |
interactive shell in the VM as the unprivileged workload user |
agent |
alias of shell |
export |
save ~/out as ZIP or tar.gz on the host (never extracted) |
put |
copy one host file to a new path under /home/appsec |
logs |
print the recent policy log (allowed and denied connections) |
status |
print sbx’s description of the VM (sbx inspect) |
stop |
kill switch: remove the credentials, stop the VM and its reproducers |
repro-create |
create an offline reproducer VM from this primary’s clean template |
reset |
DELETE the VM’s current state and recreate it from the clean template |
destroy |
remove the VM and its reproducers entirely |
admin |
root maintenance shell (outside the workload boundary) |
create
Section titled “create”Create the sandbox VM, bootstrap the harness, lock the network policy to the provider’s endpoint plus the chosen package registry, and save a clean template that reset and repro-create start from. Takes a few minutes. Provider and harness are fixed for the life of the VM: to change them, destroy and create again. Refuses while sbx’s bindings file approves the credential of another appsec-sbx VM, which sbx would attach to this one.
usage: appsec-sbx create [-h] [--provider {anthropic,claude-code,codex,deepseek,openrouter} | --endpoint HOST:PORT] [--key-var NAME] [--harness {opencode,claude-code,codex,pi}] [--registry NAME|HOST:PORT | --no-registry] [name]
positional arguments: name name for the new sandbox (default appsec-sbx)
options: -h, --help show this help message and exit --provider {anthropic,claude-code,codex,deepseek,openrouter} model provider preset; decides the allowlist, the key variable and the default harness (default openrouter) --endpoint HOST:PORT one exact model endpoint instead of a preset; needs --key-var --key-var NAME with --endpoint: environment variable the harness reads the key from --harness {opencode,claude-code,codex,pi} agent harness installed by the bootstrap (default follows the provider: claude-code for the Claude seat, codex for Codex, otherwise opencode; pi is an opt-in alternative to opencode for API-key providers) --registry NAME|HOST:PORT package registry the workload may reach; repeatable; a name (npm, pypi) or an exact HOST:PORT such as an organisation mirror (default npm) --no-registry allow no package registry at allverify
Section titled “verify”Check the mounts, published ports, policy and MCP inventory the wrapper requires, then print the guest’s tool versions and the result of its runsc probe. Run it after create and whenever a run behaves unexpectedly.
usage: appsec-sbx verify [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitimport
Section titled “import”Copy the tracked working-tree contents of a local checkout (edits included, no Git metadata) into the guest. Untracked files, .env*, common credential files and agent or editor configuration directories are excluded. A tracked symlink whose target, read from the Git index, is an imported file or directory inside the repository is recreated in the guest; other links are skipped and listed, never followed. Hardlinks, special files and traversal paths are rejected; limits are 64 MiB per file and 512 MiB in total. A manifest with per-file SHA-256 values and the link targets is written beside host state (import.json). An existing target is kept unless –replace is given. Public GitHub URLs are fetched into a temporary host checkout; –ref selects a branch, tag or commit (default: main). The URL, requested ref and resolved commit are recorded in import.json. The guest needs no GitHub access. Private repositories require a local checkout. Use reset before an independent review; –replace only swaps the target files.
usage: appsec-sbx import [-h] [--ref REF] [--replace] [name] source
positional arguments: name sbx sandbox name (default appsec-sbx) source local Git checkout or public https://github.com/OWNER/REPO URL
options: -h, --help show this help message and exit --ref REF GitHub branch, tag or commit (default: main); URLs only --replace remove an existing ~/target/source first (harness state, ~/out and the key stay)skills
Section titled “skills”Install the immediate subdirectories of a Git checkout that contain a SKILL.md into the selected harness’s user-level skills directory; everything else in the checkout is skipped and counted. Records the checkout’s commit, a dirty flag and per-file hashes beside host state (skills.json). Skill names use lowercase letters, digits and single hyphens. Names already installed are refused unless –replace is given. GitHub URLs are fetched into a temporary host checkout; –ref defaults to main and –subdir selects the pack directory. Records the URL, requested ref and resolved commit. The guest needs no GitHub access. Private repositories require a local checkout.
usage: appsec-sbx skills [-h] [--ref REF] [--subdir SUBDIR] [--replace] [name] source
positional arguments: name sbx sandbox name (default appsec-sbx) source local pack directory or public https://github.com/OWNER/REPO URL
options: -h, --help show this help message and exit --ref REF GitHub branch, tag or commit (default: main); URLs only --subdir SUBDIR pack directory within the GitHub repository (default: root); URLs only --replace overwrite skills of the same nameRead the key from the environment variable named by the provider profile, or prompt for it without echo, and store it in sbx’s credential store scoped to this VM. The guest never receives the key: the workload sees the placeholder proxy-managed in the key variable, and sbx’s host-side proxy puts the real value into requests to the provider’s host. The stored key survives idle stops; unkey or stop removes it. shell --key stores the key and enters in one step.
usage: appsec-sbx key [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitRemove this VM’s key from sbx’s credential store, which stops the proxy adding it at once, and delete the harness credential stores on the workload user’s home (Claude Code, Codex, OpenCode). Running processes keep tokens they already hold; revoking a key or seat at the provider is a separate action.
usage: appsec-sbx unkey [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitRun a single command as the unprivileged workload user and return its exit status. Write the command after --. An exec that stays open (for example -- sleep 7200) counts as a session and keeps the VM from stopping during an unattended run.
usage: appsec-sbx exec [-h] [--key] [name] ...
positional arguments: name sbx sandbox name (default appsec-sbx) command the command, written after --
options: -h, --help show this help message and exit --key store the provider key first (as `key`), then enter; for exec, write it before the nameEnter the VM as the workload user (no sudo, no Docker, clean environment) in ~/target/source. –key stores the provider key first (as key), then enters.
usage: appsec-sbx shell [-h] [--key] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exit --key store the provider key first (as `key`), then enter; for exec, write it before the nameSame as shell.
usage: appsec-sbx agent [-h] [--key] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exit --key store the provider key first (as `key`), then enter; for exec, write it before the nameexport
Section titled “export”Archive the workload’s ~/out directory inside the VM and copy it to a new host file. The filename selects the format: .zip for ZIP, .tar.gz or .tgz for gzip-compressed tar (case-insensitive). ZIP includes regular files and directories, and refuses symlinks and special files. Existing host files are never overwritten; failed exports remove the incomplete file. The wrapper does not extract or sanitise archive contents. Treat them as untrusted output and extract into an empty directory for review.
usage: appsec-sbx export [-h] [name] archive
positional arguments: name sbx sandbox name (default appsec-sbx) archive new host archive: .zip, .tar.gz or .tgz (must not exist)
options: -h, --help show this help message and exitCopy a single host file into the guest. The destination must be an absolute path under /home/appsec/ that does not exist yet; directories and traversal are refused.
usage: appsec-sbx put [-h] [name] source destination
positional arguments: name sbx sandbox name (default appsec-sbx) source host file destination absolute guest path under /home/appsec/ that does not exist yet
options: -h, --help show this help message and exitPrint the last 30 entries of sbx’s policy log for this sandbox: which hosts the workload reached and which requests the profile denied, with timestamps.
usage: appsec-sbx logs [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitstatus
Section titled “status”Print sbx inspect for this sandbox as JSON: state, sessions, resources, identifiers.
usage: appsec-sbx status [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitStop the reproducer VMs created through this primary, remove the stored key from sbx (also when the VM has already stopped) and the harness login stores from a running primary, then stop it. Disk contents stay; nothing is revoked at the provider.
usage: appsec-sbx stop [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitrepro-create
Section titled “repro-create”Create a second VM from the primary’s clean template (tools installed, nothing imported) with no network at all and no model key, recorded as a reproducer of this primary so that stop and reset include it. Use import, shell, exec and export on it under its own name; key refuses it.
usage: appsec-sbx repro-create [-h] [name] new_name
positional arguments: name name of the primary VM (default appsec-sbx) new_name name for the new reproducer VM
options: -h, --help show this help message and exitRemove the primary and its recorded reproducers, then create the primary again from the template saved by create. The installed tools stay; the imported target, ~/out, installed skills, harness state and login stores are gone. export first, run skills again afterwards. Reset is required before each independent review, including repeat passes and comparisons. Resuming the same interrupted review can keep its state.
usage: appsec-sbx reset [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitdestroy
Section titled “destroy”Remove the primary and its recorded reproducers from sbx, and its credential binding unless another VM uses it; sbx reads that removal after sbx daemon restart. The host state directory and the saved template are kept.
usage: appsec-sbx destroy [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exitEnter the VM as root for trusted setup work. Nothing done here is contained by the workload boundary; do not run the agent from it.
usage: appsec-sbx admin [-h] [name]
positional arguments: name sbx sandbox name (default appsec-sbx)
options: -h, --help show this help message and exit