Turn On the Command Sandbox

Permission rules decide whether Kiro may run a command. The command sandbox limits what that command can reach once it is running. Kiro added it to the IDE (1.3) and the CLI (2.31.0) on 13 October 2026.

When to use this

Turn it on before you let an agent run shell commands without watching each one: Autopilot, the CLI’s /autonomous on, a headless CI job, or any repository you did not write. On a personal project where you approve every command it adds little.

Know what it covers before you rely on it:

Inside the sandbox	Outside the sandbox
Terminal commands the agent runs, and every child process	The agent harness and its conversation with the model
Local stdio MCP servers, if you turn on mcpSandboxing	Built-in file tools (permission rules still govern them)
	Remote HTTP and SSE MCP servers

It applies only to sessions on your machine. Cloud sessions already run in a managed cloud sandbox.

Steps

1. Check your platform. macOS needs nothing; Kiro uses the built-in Seatbelt sandbox. Linux needs Bubblewrap (bwrap) on your PATH, plus socat if you will use COMMON_DEPENDENCIES or allow specific hosts; Kiro does not install them. Windows needs a one-time administrator setup: the IDE prompts for it, and in the CLI you run /sandbox setup (use CLI 2.31.1 or later if policy blocks programs in %TEMP%).

2. Open the configuration. IDE: select Command sandbox in the status bar; Kiro opens the project file if one exists, otherwise your global file, creating {"enabled": false} if neither does. CLI: run /sandbox in a local V3 session.

3. Turn it on and pick a network mode.

   Example: ~/.kiro/settings/sandbox.json

   {
     "enabled": true,
     "networkAccess": "COMMON_DEPENDENCIES"
   }

   networkAccess	Outbound network from sandboxed commands
   DEFAULT_BLOCKED	Blocked, except hosts you allow. The default
   COMMON_DEPENDENCIES	Common package, source, build, and container services; everything else blocked
   DEFAULT_ALLOWED	Open. sandbox_network deny rules are not reliable here

   The values are case-sensitive and unknown keys are ignored.

4. Allow the extra hosts your build needs with sandbox_network rules in permissions.yaml. Unlike other capabilities, the first matching rule wins, so list specific hosts before broader *.suffix wildcards. capability: all does not include sandbox_network.

   # ~/.kiro/settings/permissions.yaml
   rules:
     - capability: sandbox_network
       match: ['packages.internal.example.com']
       effect: allow

5. Decide on MCP. Set "mcpSandboxing": true to start local stdio MCP servers inside the same sandbox. Changing it restarts local MCP servers, which can take about a minute.

6. Decide the scope. A global policy applies everywhere. A project file can turn the sandbox on for one repository, or tighten an active global policy, but cannot disable it, open the network further, or turn off global MCP wrapping. A cloned repository therefore cannot loosen your settings.

7. For unattended CLI work, use /autonomous on in a local V3 session. Kiro switches to the Default agent, turns the sandbox on, and stops asking you to approve each shell command. For V3 headless runs (2.31.0 and later), a saved sandbox.json with enabled: true applies automatically; add --sandbox when the run must stop rather than continue without protection.

Check it worked

In the IDE the status bar reads Active (it shows Applying while a change loads, Error if the change failed and the old settings stayed, and Unavailable if the platform backend is missing). Then ask the agent to fetch a URL with curl from a host you have not allowed. Under DEFAULT_BLOCKED the command should fail to connect; add an allow rule and it should succeed.

Common problems

• Status says Unavailable. The backend is missing: bwrap on Linux, or the Windows administrator setup. Until you fix it, commands run without operating-system isolation. Reload the IDE window or start a new CLI session afterwards.
• A build cannot download dependencies. Switch to COMMON_DEPENDENCIES, or add a sandbox_network allow rule for the host.
• Windows refuses COMMON_DEPENDENCIES or DEFAULT_ALLOWED. Complete the one-time setup. DEFAULT_BLOCKED works before it.
• The agent still edited a file you wanted protected. Built-in file tools are outside the sandbox. Use deny rules in permissions.yaml and .kiroignore for files.
• An MCP server is not covered. Wrapping failed for that server; command sandboxing is still active. Check the server’s command and MCP logs.

Related

• Set up permissions.yaml decides what the agent may do at all.
• Run Kiro CLI headless in CI is where an unattended sandbox matters most.
• Keep secrets out with .kiroignore covers files, which the sandbox does not.