Shell sandbox

The shell sandbox runs each command the agent starts inside your operating system’s own sandbox. A sandboxed command can write only where you allow, cannot see your credential folders, and reaches the network only for hosts you approve. It is a second fence behind permission rules: even a command you approved cannot wander off.

The sandbox is off until you turn it on. It applies to commands the agent runs through the Bash tool. Hooks and MCP servers are started without it.

Turn it on

/sandbox with no arguments shows the current state: on or off, which sandbox program, network access, writable folders and excluded commands. A /sandbox choice beats the environment variable, which beats the settings file.

Check that it works

Turn it on, then ask the agent to run something that should fail:

> /sandbox on
> run: touch ~/sandbox-test && echo created

The write outside the working folder is refused by the operating system, and the agent sees the error. A command inside your project still works as normal.

What a sandboxed command may do

Credentials stay hidden

When a command runs in the sandbox, these folders and files in your home folder are masked, even if you run in your home folder or allow reads of ~:

.ssh, .gnupg, the credential folders of cloud command-line tools, .kube, .docker/config.json, .netrc, .npmrc, .pypirc, .git-credentials, .config/gh/hosts.yml, and Syntic’s own .syntic folder.

Secret-looking environment variables are removed too. That covers well-known names such as cloud access keys and database passwords, and any variable whose name ends in TOKEN, SECRET, PASSWORD, PASSWD, PAT, APIKEY, API_KEY, ACCESS_KEY, SECRET_KEY, PRIVATE_KEY or AUTH_TOKEN. Values you set for the session with /env are passed through on purpose. Syntic Code’s own sign-in is never passed to any command, sandboxed or not.

Settings

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["paste.example"]
    },
    "filesystem": {
      "allowWrite": ["~/.cache/build"],
      "denyWrite": ["./secrets"],
      "denyRead": ["~/private/**"]
    },
    "excludedCommands": ["docker *"]
  }
}

How files combine

Settings from every file are merged, with stronger files winning for single values. The deny lists (deniedDomains, denyWrite, denyRead) are different: entries from every file add up, so no file can remove another file’s deny entry.

A repository’s own settings can only make the sandbox stricter. From .syntic/settings.json or .syntic/settings.local.json, only these are read: enabled, strictCwd and failIfUnavailable when set to true, and the three deny lists. A project cannot allow hosts, add writable folders, exclude commands, permit unsandboxed runs or change bwrapPath.

Network rules

The operating system can only switch networking fully on or off for a process; it cannot filter by host. So Syntic Code looks at each command and decides before it starts:

1. If the command uses a denied host, it is refused before it runs, and you are told which entry matched. This beats every way of turning the network on.
2. If every host the command uses is allowed (or allowedDomains holds *), it gets the network.
3. Otherwise it runs with the network off. If it then fails, the agent gets a note that a host was not on the list.

Hosts are found in:

• URLs (https://host/...), user@host:path remotes, and host arguments to network tools such as curl, wget, ssh, scp and nc;
• the default registry of a package manager the command clearly uses: npm, pnpm and yarn; pip, uv and poetry; cargo; gem and bundle; go; brew. A --registry or --index-url on the command replaces the default;
• git remotes: git clone, fetch, pull, push and ls-remote without a URL use the remote’s address from .git/config.

A command that names no host it can see gets the network only when allowedDomains holds *.

/sandbox network on and SYNTIC_BASH_SANDBOX_NET=1 switch the network on for every sandboxed command, except those that name a denied host.

Running a command outside the sandbox

Some tools do not work in a sandbox: container engines, tools that talk to system services, or builds that write to many places. You have two ways out:

• excludedCommands: list commands that should always run normally. They still go through the usual permission prompt.
• allowUnsandboxedCommands: lets the agent mark one call as needing to run outside. Without this setting (or SYNTIC_BASH_ALLOW_UNSANDBOXED=1), such a request is ignored and the command stays sandboxed, so the model can never turn the fence off by itself.

How the sandbox relates to permissions

The sandbox and permission rules work at different moments. Rules decide whether a command runs; the sandbox limits what it can touch once it does.

For organizations

Put the sandbox block in managed settings to set it for everyone. Two policy-only switches stop users from widening it:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "network": { "allowedDomains": ["github.example.com", "registry.npmjs.org"], "allowManagedDomainsOnly": true },
    "filesystem": { "allowRead": ["/opt/tools"], "allowManagedReadPathsOnly": true }
  }
}

With allowManagedDomainsOnly, users’ allowedDomains entries are ignored and only the policy’s count. allowManagedReadPathsOnly does the same for allowRead. Deny lists from users and projects still add up on top.

Environment variables

Troubleshooting