The local command sandbox adds an operating-system boundary around shell commands run by Kiro's agent harness. It limits what each command and child process can reach without moving the agent itself into the sandbox.
The agent harness stays outside the sandbox. Before a shell command starts, permissions decide whether Kiro may run it. The sandbox then limits what the running command and its child processes can reach.
Inside the sandbox:
Outside the sandbox:
The sandbox applies only to sessions running on your machine. Cloud sessions use the managed cloud sandbox instead.
The sandbox reduces what a command can do; it is not a guarantee of isolation. Keep reviewing proposed commands, and keep deny rules for operations that must never run.
| Platform | Requirement |
|---|---|
| macOS | None. Kiro uses the built-in Seatbelt sandbox through sandbox-exec. |
| Linux | Bubblewrap (bwrap) on your PATH. Kiro does not install it. COMMON_DEPENDENCIES, and DEFAULT_BLOCKED with allowed hosts, also need socat. Install both through your distribution's package manager. |
| Windows | One administrator setup before COMMON_DEPENDENCIES or DEFAULT_ALLOWED can run commands. Kiro IDE prompts you to complete it. In Kiro CLI, run /sandbox setup. DEFAULT_BLOCKED works before setup. |
When the platform backend is missing, Kiro reports the sandbox as unavailable. Commands then run without operating-system isolation unless the current mode requires protection.
Select Command sandbox in the status bar. Kiro opens the active configuration file: the project file when one exists, otherwise your global file. If neither file exists, Kiro creates a global file containing {"enabled": false}.
To open the global file directly, run Open User Sandbox Config (JSON) from the command palette.
Set enabled to true, then choose a network mode:
{ "enabled": true, "networkAccess": "COMMON_DEPENDENCIES" }
Save the file. Valid changes apply to the running session. The status bar shows Applying, then Active.
| State | Meaning |
|---|---|
| Off | No active configuration enables the sandbox. |
| Active | Commands use the current sandbox and network mode. |
| Applying | Kiro is applying a configuration change. |
| Error | The change failed. The prior settings stay active. |
| Unavailable | The platform backend is missing. Commands run without operating-system isolation. |
The tooltip also reports when requested MCP wrapping is unavailable.
Both clients read sandbox.json at global and project levels:
| Scope | Path | Use for |
|---|---|---|
| Global | Kiro IDE: ~/.kiro/settings/sandbox.json. Kiro CLI: $KIRO_HOME/settings/sandbox.json when set, otherwise ~/.kiro/settings/sandbox.json. | Your default policy across projects. |
| Project | <workspace-root>/.kiro/settings/sandbox.json | Turning the sandbox on, or tightening it, for one repository. |
In a multi-root IDE workspace, only the first workspace folder supplies the project file.
| Key | Required | Values | Default |
|---|---|---|---|
enabled | Yes | true, false | |
networkAccess | No | DEFAULT_BLOCKED, COMMON_DEPENDENCIES, DEFAULT_ALLOWED | DEFAULT_BLOCKED |
mcpSandboxing | No | true, false | false |
networkAccess values are case-sensitive. Unknown keys are ignored.
enabled to false, choose a more open network mode, or turn off MCP wrapping enabled globally.enabled: false, a project file with enabled: true turns on the sandbox for that project.A repository you clone cannot use its project file to open network access or disable an active global sandbox policy.
networkAccess sets the starting point for outbound network access from sandboxed commands. Your sandbox_network permission rules refine it.
| Mode | Outbound network |
|---|---|
DEFAULT_BLOCKED | Blocked, except hosts allowed by a sandbox_network rule. This is the default. |
COMMON_DEPENDENCIES | Common package, source, build, and container services are reachable. Other hosts stay blocked unless a rule allows them. |
DEFAULT_ALLOWED | Open. Sandboxed commands can reach any host. Do not rely on sandbox_network deny rules in this mode. |
Use DEFAULT_BLOCKED for the tightest network control. Use COMMON_DEPENDENCIES when normal installs and builds need common development services. Use DEFAULT_ALLOWED only when network filtering is not required.
sandbox_network is a permission capability. Host rules are applied in order. The first matching rule decides, unlike other permission capabilities where a deny always wins. Put specific hosts before broader wildcards that also match them.
Patterns are case-insensitive. They support exact host names and *.suffix wildcards.
# ~/.kiro/settings/permissions.yaml rules: - capability: sandbox_network match: ['packages.internal.example.com'] effect: allow # Keep this rule before the wildcard below. - capability: sandbox_network match: ['uploads.example-corp.net'] effect: deny - capability: sandbox_network match: ['*.example-corp.net'] effect: allow
Workspace rules in ~/.kiro/workspace-roots/<hash>/permissions.yaml work the same way for one project.
sandbox_network is not part of the all meta-capability. capability: all, effect: allow does not open sandboxed network access. Your fs_read and fs_write rules also shape which paths sandboxed commands can see and write.
Set mcpSandboxing to true to start stdio MCP server processes inside the same sandbox as shell commands:
{ "enabled": true, "networkAccess": "DEFAULT_BLOCKED", "mcpSandboxing": true }
Remote HTTP and SSE MCP servers are not affected. Changing mcpSandboxing restarts local MCP servers, which can take about a minute. If wrapping fails for a server, command sandboxing stays active and Kiro reports that the server is not covered.
A project cannot turn off MCP wrapping enabled globally. Set it globally when you want it across projects, or in one project file when only that repository needs it. See MCP security best practices for broader server guidance.
A command cannot reach a host. Add a sandbox_network allow rule. You can also use COMMON_DEPENDENCIES for a common development service.
The sandbox is unavailable. On Linux, check that bwrap is on your PATH. Install socat when proxy filtering is needed. On Windows, complete the administrator setup. Until you fix the cause, commands run without operating-system isolation. After fixing it, reload the IDE window or start a new CLI session.
Windows refuses COMMON_DEPENDENCIES or DEFAULT_ALLOWED. Complete the one-time setup from the IDE prompt, or run /sandbox setup in CLI. You can use DEFAULT_BLOCKED before setup.
MCP servers are not covered. Wrapping failed for one or more stdio servers. Shell command sandboxing remains active. Check the server command and MCP logs or status. Saving a changed mcpSandboxing value restarts local MCP servers.
The status bar shows Error. The file is malformed or unreadable, or Kiro could not apply the change. Prior settings stay active. Fix the JSON and save it again. Use Reload Window when Kiro offers it.
sandbox_network, fs_read, and fs_write
Local command sandbox