VM lifetime, reset and policy
Idle stop, sessions and credentials
Section titled “Idle stop, sessions and credentials”sbx stops a local VM about a minute after its last session ends. A session is
an interactive shell or a running exec command. Commands that enter the VM
or transfer files restart it automatically if it has stopped. The message
Sandbox <name> started successfully tells you that a restart occurred.
sbx idle stop, or sbx stop |
wrapper stop / unkey |
|
|---|---|---|
Disk: installed tools, imported target, ~/out, skills, harness state and databases |
kept | kept; reset returns to the clean template, which keeps the tools and drops the target, ~/out, installed skills, harness state and any login store (reinstall skills after a reset) |
API key stored by key (held by sbx on the host; the guest sees only a placeholder) |
kept | removed, also from a stopped VM |
Harness login stores on the agent’s home (~/.claude/.credentials.json, ~/.codex/auth.json, ~/.pi/agent/auth.json, OpenCode’s auth.json) |
kept: a seat’s refresh token stays in the VM | unkey removes them; stop attempts removal only while the VM is running |
| Reproducer VMs | untouched | stopped with the primary |
| Server-side validity of the key or seat | unchanged | unchanged; revocation is a separate action |
An idle stop is not the kill switch. The stored API key and a browser-login credential
both survive it, and nothing is revoked at the provider. stop and unkey remove the
stored key whether or not the VM is running; unkey also clears known login files, which
stop does only while the VM runs, ignoring deletion errors. After the review, run stop
(or unkey first for a seat login) and revoke the credential at the provider. See
M23 for the remaining login-store gap.
- Interactive runs:
shell --keystores the key and opens a shell in one step;keyalone works too, since the stored key survives the idle stop. When you enter a VM configured for a model provider, the wrapper printsNOTE: no model credential is stored ...if neither a stored key nor a harness login exists. - Unattended runs (
execof a harness command, a detached process started inside the guest): hold one session open for the duration, for exampleappsec-sbx exec appsec-sbx -- sleep 7200in a second terminal, so the VM does not stop mid-run. - Subscription logins (Claude Code, Codex login): saved login files survive
idle stops, so the VM can still use the subscription account after restarting.
End a working session with
unkeyfollowed bystop, and revoke the login at the provider. - Reading records: phase timings and policy-log timestamps are unaffected; the VM’s
uptimeinsbx inspectrestarts at every wake and says nothing about the run.
Check network denial
Section titled “Check network denial”After create and verify, run these checks before importing code or adding
a credential. Repeat them after changes to the host network, VPN, proxy or
sandbox policy. verify checks entry conditions; these commands test actual
requests from the unprivileged workload user. The missing-credential notice
is expected here.
Run each command separately from the host terminal, including PowerShell on
Windows. curl runs inside the Linux VM. Each request has a ten-second limit
and should fail. Read the logs immediately after each request: logs shows
only the latest 30 entries.
First, try a raw IP address with the VM’s usual proxy settings:
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 https://1.1.1.1appsec-sbx logs appsec-sbxThen bypass curl’s proxy settings for the same address:
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 --noproxy '*' https://1.1.1.1appsec-sbx logs appsec-sbxFinally, try a hostname outside the allowlist, also bypassing curl’s proxy
settings. example.com is denied by the standard provider profiles:
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 --noproxy '*' https://example.comappsec-sbx logs appsec-sbxFor each request, record the command, time, error and matching denial from this VM’s policy log. The log must identify the requested destination and a blocking rule or policy reason. A proxy 403, TLS connection closure or DNS failure may accompany a denial. A timeout, certificate error or failed lookup alone is inconclusive. Resolve missing denial evidence or unexpected access before starting the review; keep the restrictions in place.
On sbx 0.49.1 and later, a request that matches no rule, such as the raw-address
probes, also raises an approval request. List them with sbx policy approval ls
and dismiss each one with sbx policy approval respond <id> --option dismiss.
Do not approve one for a review VM: approval adds an allow rule.
These checks cover the tested HTTPS paths. They do not establish full DNS, UDP, IPv6 or host/LAN isolation. Allowed hostnames that resolve to private addresses are refused on sbx 0.49.1 and later; earlier releases do not check them. See the network requirements and coverage limits.
Reproducers and container-based setups
Section titled “Reproducers and container-based setups”For a separate reproducer VM, repeat the checks with its name before running generated code. Also test the primary VM’s allowed model and registry hosts: the reproducer should deny those too.
The standard appsec user has no sudo or Docker access, so there is no
container probe in this routine check. Keep those restrictions. If you add a
container-based workload, test from inside each container network mode you
will use, with client proxy settings bypassed, and collect matching denial
logs. That setup needs separate validation before use; an administrator’s
container test alone does not validate the workload’s access.
Test the kill switch
Section titled “Test the kill switch”Complete this rehearsal on a newly created VM before importing project code or asking an agent to do any work. Repeat it if you change the credential type, provider or stop procedure. Keep the provider’s credential-management page available on the host.
For an API key, use a temporary, capped key that you can revoke after the test. In the first host terminal, start a harmless command:
appsec-sbx exec --key appsec-sbx -- sleep 600For a subscription login, enter with appsec-sbx shell appsec-sbx. From the
guest home directory, start claude and use /login, or run
codex login --device-auth. Submit no review prompt. Exit the harness and
run sleep 600 in the guest shell. Keep that session open for the test.
See Providers and credentials for login details.
While the command is still running, use a second host terminal:
appsec-sbx stop appsec-sbxappsec-sbx status appsec-sbxConfirm that the first terminal’s command ended and the VM status is stopped. If you use reproducer VMs, repeat the test with a harmless command running in one and check its status too; stopping the primary must stop its reproducers.
Revoke the test API key or subscription login at the provider. Record the provider’s confirmation; deleting a local credential file does not revoke it. Then restore the clean VM and check that it can start again:
appsec-sbx reset appsec-sbxappsec-sbx verify appsec-sbxRecord the stop result, credential revocation and successful reset. Resolve any failed step before the first review. Supply a fresh capped key or a new login when you start that review, after importing the target and skills.
Reproducers, reset and destroy
Section titled “Reproducers, reset and destroy”A reproducer is a small program used to check whether a reported vulnerability is real. A reproducer VM runs that program separately from the review agent. The wrapper creates it from the clean template, with tools installed, no imported project data and no model credential. Its network policy denies all destinations. The network checks above describe the validation required before running generated code there.
appsec-sbx repro-create appsec-sbx appsec-sbx-reproappsec-sbx import appsec-sbx-repro /absolute/path/to/git-repositoryappsec-sbx shell appsec-sbx-repro# Or a bounded command without an interactive shell:appsec-sbx exec appsec-sbx-repro -- timeout 60 python3 /home/appsec/target/source/reproduce.pyappsec-sbx export appsec-sbx-repro ./reproducer-results.zip
appsec-sbx stop appsec-sbx # also stops the reproducers created through this primaryappsec-sbx reset appsec-sbx # DELETES the primary's state and its reproducers, recreates from the clean templateappsec-sbx destroy appsec-sbx # removes the primary and its reproducers entirelyReset is required before every independent review: a new target, a repeat discovery pass, or a comparison with another model, prompt or skill pack. Resuming an interrupted review of the same target can retain its state.
Export any results you need, stop the run and revoke its credential before
resetting. reset removes the target, ~/out, installed skills, harness state
and login stores, and removes associated reproducers. It restores the tools
from the clean template. Run verify, import the target, reinstall skills
and supply a fresh credential with a budget before the next review.
import --replace keeps tools, harness state, output and credentials; it
cannot provide a clean start for an independent review.
destroy also removes the VM’s credential binding unless another VM uses it. Run
sbx daemon restart before creating a VM for another provider; the
provider guide
explains why.
During reset or repro-create, sbx may warn that the template “was built
for the shell agent but you are using appsec-shell”. The names refer to
the template’s base image and the wrapper’s shell setup. Run verify on the
restored VM and resolve any failed checks before using it.
Global sbx policy
Section titled “Global sbx policy”The wrapper adds sandbox-scoped rules and leaves your global policy and other sandboxes
alone. It needs a global policy it can narrow: initialise a fresh installation with
sbx policy init deny-all (Docker calls this preset Locked Down). balanced also works but
its default-ai-services rule overlaps the Codex preset, and create then refuses with the
rule’s name; the fix is sbx policy rm network --id default-ai-services, which affects every
sandbox on the machine. An inherited ** allow cannot be narrowed and is refused.
Any later edit to the global or scoped policy makes the next workload entry fail and stops the
affected VM family; reset recompiles the policy from the clean baseline. An sbx upgrade can
have the same effect when the release changes how rules are reported (0.45.0 did): VMs created
on the older release are refused with “Policy changed since provisioning” until you reset
them, or destroy and recreate them.