Skip to content

VM lifetime, reset and policy

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 --key stores the key and opens a shell in one step; key alone works too, since the stored key survives the idle stop. When you enter a VM configured for a model provider, the wrapper prints NOTE: no model credential is stored ... if neither a stored key nor a harness login exists.
  • Unattended runs (exec of a harness command, a detached process started inside the guest): hold one session open for the duration, for example appsec-sbx exec appsec-sbx -- sleep 7200 in 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 unkey followed by stop, and revoke the login at the provider.
  • Reading records: phase timings and policy-log timestamps are unaffected; the VM’s uptime in sbx inspect restarts at every wake and says nothing about the run.

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:

Terminal window
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 https://1.1.1.1
appsec-sbx logs appsec-sbx

Then bypass curl’s proxy settings for the same address:

Terminal window
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 --noproxy '*' https://1.1.1.1
appsec-sbx logs appsec-sbx

Finally, try a hostname outside the allowlist, also bypassing curl’s proxy settings. example.com is denied by the standard provider profiles:

Terminal window
appsec-sbx exec appsec-sbx -- curl -q -I -sS -f --connect-timeout 5 --max-time 10 --noproxy '*' https://example.com
appsec-sbx logs appsec-sbx

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

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.

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:

Terminal window
appsec-sbx exec --key appsec-sbx -- sleep 600

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

Terminal window
appsec-sbx stop appsec-sbx
appsec-sbx status appsec-sbx

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

Terminal window
appsec-sbx reset appsec-sbx
appsec-sbx verify appsec-sbx

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

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.

Terminal window
appsec-sbx repro-create appsec-sbx appsec-sbx-repro
appsec-sbx import appsec-sbx-repro /absolute/path/to/git-repository
appsec-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.py
appsec-sbx export appsec-sbx-repro ./reproducer-results.zip
appsec-sbx stop appsec-sbx # also stops the reproducers created through this primary
appsec-sbx reset appsec-sbx # DELETES the primary's state and its reproducers, recreates from the clean template
appsec-sbx destroy appsec-sbx # removes the primary and its reproducers entirely

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

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.