Skip to content

Providers and credentials

Exactly one model provider per VM. The provider decides the workload allowlist, the key variable and, unless --harness says otherwise, the installed harness: claude-code installs Claude Code, codex installs the Codex CLI, every other provider installs OpenCode. --harness pi installs Pi instead of OpenCode for any API-key provider. Changing the provider or harness means a new VM (destroy, then create).

create option Allowlist (plus the registry) Credential Harness
--provider openrouter (default) openrouter.ai:443 OPENROUTER_API_KEY via shell --key OpenCode
--provider anthropic api.anthropic.com:443 ANTHROPIC_API_KEY via shell --key OpenCode
--provider deepseek api.deepseek.com:443 DEEPSEEK_API_KEY via shell --key OpenCode
--provider claude-code api.anthropic.com:443, platform.claude.com:443 browser login from the guest (/login), or CLAUDE_CODE_OAUTH_TOKEN Claude Code
--provider codex api.openai.com:443, auth.openai.com:443, chatgpt.com:443 OPENAI_API_KEY via shell --key, or codex login --device-auth in the guest Codex CLI
--endpoint HOST:PORT --key-var NAME that one exact endpoint NAME via shell --key OpenCode

--harness pi replaces OpenCode on any API-key row; see Pi on an API key.

Wildcards are refused. --registry is repeatable and takes npm, pypi or an exact HOST:PORT such as an organisation mirror; --no-registry allows none. Pick the registry the target needs if the agent is meant to install its dependencies: a Python target under an npm-only profile will show dozens of denied PyPI connections in the log and no installed dependencies. A discovery-only prompt is not a control; the allowlist is.

API key (OpenRouter, Anthropic, DeepSeek, custom endpoint)

Section titled “API key (OpenRouter, Anthropic, DeepSeek, custom endpoint)”

shell --key (also agent --key, exec --key) prompts for the key without echo, or takes it from the environment variable of the same name, stores it in sbx’s credential store scoped to this VM, and enters. key alone does the same without entering; unkey, stop, reset and destroy remove the stored key, also from a stopped VM. The key never enters the VM: while a key is stored, every session you enter carries the key variable with the placeholder proxy-managed, and sbx’s proxy puts the real value into requests to the provider’s host (x-api-key for Anthropic, Authorization: Bearer otherwise). Sessions entered without a stored key have no key variable, so the harness asks for a provider instead of failing on a request. A copied placeholder is useless elsewhere, but every request the workload sends to that host carries the key, so any process in the VM can spend it. The budget is whatever cap the key carries at the provider. The stored key survives the VM’s idle stop; see VM lifetime.

sbx keeps the key in the host’s credential store: the macOS Keychain, the Windows Credential Manager, a desktop keyring on Linux, or a file under ~/.config/com.docker.sandboxes on a Linux host without one. The wrapper also writes an approval for its kit’s credential to sbx’s bindings file (~/.config/sbx/credentials.yaml, %APPDATA%\sbx\credentials.yaml on Windows) so that create runs without a prompt. VMs created by wrapper versions before 0.4.0 cannot take a key this way; destroy and create them again.

sbx attaches every binding in that file to each VM it creates, and the entry guard refuses a VM that carries another VM’s credential. Keyed VMs of different providers therefore cannot run side by side. create and reset refuse while the file binds another wrapper VM’s appsec- service and name the entry and the VM that uses it. destroy removes the VM’s own binding unless another VM uses it. sbx reads a removal only after a daemon restart, so run sbx daemon restart after destroy or after removing an entry by hand, before you create a VM for another provider. Your own bindings under other names stay untouched.

Before the first review with your chosen credential type, complete the kill-switch rehearsal, including provider-side revocation. Use a fresh credential for the review. Before each later independent review, follow Starting another review.

create appsec-sbx --provider openrouter --harness pi (any API-key preset or custom endpoint works the same). Pi reads the provider’s key variable from the environment, so shell --key is the credential path; /login inside the guest would write a key to ~/.pi/agent/auth.json, which unkey and stop remove. The seeded ~/.pi/agent/settings.json refuses project configuration under the imported target (defaultProjectTrust: never, so a repository’s .pi directory and .agents/skills never load), sets OpenRouter as the default provider and turns install telemetry off; the login environment adds PI_OFFLINE=1 and PI_SKIP_VERSION_CHECK=1, so Pi makes no requests besides the model API. Pick a model with /model or start with pi --model <provider/model-id>. Skills install into ~/.pi/agent/skills/ and run as /skill:<name>.

Terminal window
appsec-sbx create appsec-sbx --provider claude-code
appsec-sbx verify appsec-sbx

Complete the kill-switch rehearsal before importing code. After its clean reset, continue with a new login:

Terminal window
appsec-sbx import appsec-sbx /absolute/path/to/git-repository
appsec-sbx skills appsec-sbx https://github.com/aai-institute/agentic-appsec-playbook --subdir sandbox/skills
appsec-sbx shell appsec-sbx
# Inside:
cd ~/target/source && claude
# /login -> "Claude account with subscription": open the printed URL in a browser on
# the HOST, paste the one-time code back. Then /model, and /security-review-repo.
# The built-in /security-review is diff-scoped and has nothing to review here.

The browser login is the intended path: the pasted code is single-use and the tokens land in the agent’s home until removed with unkey. stop attempts cleanup only on a running VM; see credential cleanup limits. The alternative, shell --key with a CLAUDE_CODE_OAUTH_TOKEN from claude setup-token, uses a long-lived bearer token, stored on the host like an API key and added to requests to api.anthropic.com only. Use browser login for this workflow. The VM runs with the whole seat’s authority, and the seat’s rate limit does not provide a per-run spend cap. A fresh VM never has a credential: if claude does not ask you to log in, run claude auth status before trusting it.

The policy may block auxiliary requests for plugin downloads, updates or MCP services. Check the destination and purpose before changing the allowlist; those features are outside the basic review workflow.

Both credential forms share the codex preset. API key: shell --key with OPENAI_API_KEY. Seat: inside the workload shell run codex login --device-auth, open the printed URL in a browser on the host and enter the code (device-code login must be enabled in the ChatGPT account first). The credential lands in ~/.codex/auth.json; unkey removes it, while stop cleanup has the limits described above. Invoke the review skill by typing $security-review-repo in the composer.

Complete the kill-switch rehearsal before that first review. Use a fresh key or login after the rehearsal’s reset.

Codex keeps its own inner sandbox on top of the VM; the seeded configuration declares ~/out writable so the report write does not stop for approval, and turns account plugins off so the VM does not need to download plugin bundles for the review. Auxiliary startup requests to GitHub may be denied by the network policy.