Skip to content

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 one
agent harness, one model provider and a filtered copy of your repository. Every action
takes the sandbox name as its first argument (default: appsec-sbx).
Before the first review, create a VM and test stop and provider-side credential
revocation. Start each independent review from a new VM or a clean reset:
verify -> import -> skills -> shell --key -> (review inside) -> export -> stop
Revoke 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/)
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 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 all

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 exit

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)

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 name

Read 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 exit

Remove 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 exit

Run 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 name

Enter 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 name

Same 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 name

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 exit

Copy 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 exit

Print 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 exit

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 exit

Stop 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 exit

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 exit

Remove 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 exit

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 exit

Enter 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