Configure the agent sandbox

By the end of this tutorial, every installed AI agent host on your machine that supports its own native sandbox has it turned on — and you know how SSG rules and provider sandboxing relate to each other.

Hand this to your AI agent

Check the sandbox posture of every AI agent host installed on this machine
and turn on sandboxing wherever it's supported. Do not run any command that
mutates state without telling me first and letting me confirm.

1. Run `ssg sandbox status --json` and summarize, per provider: is it
   installed, is sandboxing already on, and if not, what would enabling it
   change (file path + key).
2. For providers where a config-file toggle exists (Claude Code, Codex,
   Antigravity) and sandboxing is currently off, ask me for confirmation,
   then run `ssg sandbox enable` (or `ssg sandbox enable --provider=<id>`
   for just one).
3. For Cursor (GUI-only) and GitHub Copilot (vendor-managed server-side),
   don't attempt to change anything — tell me exactly where I'd go to
   toggle it myself.
4. Re-run `ssg sandbox status --json` and confirm the change took effect.

What your agent will do

Read your current sandbox posture across every provider with one read-only command.
Ask before writing anything — enabling a provider's sandbox edits that provider's own config file.
Tell you plainly when a provider can't be toggled by SSG at all (Cursor, Copilot) instead of pretending to try.

What you do yourself: approve the change, and restart the affected agent (Claude Code, Codex, or Antigravity) for the new setting to take effect — none of these apply to an already-running session.

Step by step

1. Check current posture

ssg sandbox status

Add --json for machine-readable output, or --provider=<id> to check just one. The five known providers are claude-code, codex, antigravity, cursor, and copilot.

SSG does not sandbox tool calls itself — this command reads and reports each provider's own native sandboxing setting:

Provider	What SSG toggles	Where
Claude Code	`sandbox.enabled`	`~/.claude/settings.json` — enables Claude Code's own sandbox (Seatbelt on macOS, bubblewrap + socat on Linux/WSL2; native Windows unsupported)
Codex	`sandbox_mode`	`~/.codex/config.toml` — set to `"workspace-write"`, confining file writes to the workspace
Antigravity	`enableTerminalSandbox`	`~/.gemini/antigravity-cli/settings.json` — enables Antigravity's own sandbox (nsjail on Linux, sandbox-exec on macOS, AppContainer on Windows)
Cursor	—	GUI-only setting (Cursor Settings → Agent → Sandbox). SSG can read `.cursor/sandbox.json` if it exists but cannot write it for you.
GitHub Copilot	—	Vendor-managed server-side on github.com — no local config file exists for SSG to read or write. Configure it in your repository/organization's Copilot settings.

--json output goes further than the table above — each provider entry includes installed, status (configured / not-installed / unsupported), mechanism, the exact path and key SSG would write, a plain-English detail, a how_to list of manual steps if you'd rather not use ssg sandbox enable, os_support, and a docs_url pointing at that provider's own sandboxing documentation:

{
  "id": "codex",
  "status": "configured",
  "path": "/home/you/.codex/config.toml",
  "key": "sandbox_mode",
  "os_support": "macOS, Linux (native); Windows via WSL2",
  "docs_url": "https://learn.chatgpt.com/docs/config-file/config-reference"
}

There's also a master object summarizing the aggregate: enabled (true only when every applicable provider is on), applied, and total.

2. Turn sandboxing on

ssg sandbox enable                        # every provider that supports a toggle
ssg sandbox enable --provider=claude-code # just one

Every write records the prior value first, so ssg sandbox disable reverts precisely — no --yes confirmation flag is required either way, unlike ssg firewall's destructive operations.

3. Restart the agent

The setting is read at process start. Restart Claude Code, the Codex session, or the Antigravity CLI (agy) for the change to take effect — an already-running session keeps its old sandbox posture.

4. Check it from the dashboard

The dashboard's Sandbox page shows the same per-provider status as ssg sandbox status --json, plus a master switch that reflects the aggregate state (enabled: true only when every applicable provider is configured on).

5. Understand how this relates to SSG rules

Provider sandboxing and SSG rules solve different problems and are meant to be used together, not as alternatives:

Provider sandbox (this page) — isolation enforced by the agent host itself, before your .rules ever see the call. It constrains where a process can write or whether it can reach the network at all, at the OS level.
SSG rules (.sigmashake/rules/) — policy evaluated on every tool call regardless of which host is running, with the full allow/deny/ask/force vocabulary, an audit trail, and human approval. It works identically across every supported agent, sandboxed or not.

A sandbox with no SSG rules gives you OS-level containment with no visibility or approval flow. SSG rules with no sandbox give you policy and audit but rely entirely on the rule engine catching everything. Running both means a bypass of one still has to get through the other.

Verify

ssg sandbox status --json

For each provider you enabled, confirm "status": "configured" and check the detail field describes the setting now being active. For Cursor/Copilot, "status": "unsupported" (Copilot) or "not-installed"/informational GUI guidance (Cursor) is the expected honest answer, not a failure.

If something goes wrong

Symptom	Cause	Next step
`ssg sandbox enable` reports a provider as unchanged	That provider isn't installed on this machine, or was already on	Re-run `ssg sandbox status --provider=<id>` to see the exact reason
Claude Code sandbox on Linux fails to start	Missing `bubblewrap` / `socat`	Install them (`apt install bubblewrap socat` or your distro's equivalent), then restart Claude Code
Setting reverted after a Claude Code / Codex update	The provider's own config was reset by its installer	Re-run `ssg sandbox enable --provider=<id>`
Cursor shows `not-installed` even though Cursor is on the machine	No `.cursor/sandbox.json` exists yet — Cursor's sandbox is a GUI-only toggle SSG can only read, not create	Open Cursor Settings → Agent → Sandbox and toggle it there once; SSG will then read the resulting state
You want to turn everything back off	`ssg sandbox disable` reverts every provider (or `--provider=<id>` for one) to its exact prior value	No confirmation flag needed, same as enable

Use the governed terminal — every command run inside it is governed by SSG rules regardless of provider sandbox state.
Manage the host firewall — a second, host-level layer for network egress.
Allow the network domains your agent may reach — policy-level control that applies whether or not a provider sandbox is on.

Hand this to your AI agent​

What your agent will do​

Step by step​

1. Check current posture​

2. Turn sandboxing on​

3. Restart the agent​

4. Check it from the dashboard​

5. Understand how this relates to SSG rules​

Verify​

If something goes wrong​

Next​