Skip to main content
Symbiotic Code integrates with Docker Sandboxes (sbx) to run the agent’s shell commands in an isolated environment. When the sandbox is enabled, every command run by the bash tool executes inside a lightweight microVM instead of directly on your machine, so the agent can run tests and scripts without access to the rest of your system.

​
Why use Agent Sandboxing?

When AI agents run directly on a host machine, their shell commands have access to the user’s files, SSH keys, shell history, environment variables, and local network. With the Agents container enabled:
  • Isolated runtime: Shell commands run inside a microVM with its own Linux kernel, filesystem and network. Only your project folder is shared with it.
  • Workspace boundary: File tools (read, write, edit, glob, grep, apply_patch) are blocked from accessing files outside your project folder.
  • Network control: Outbound connections from the sandbox follow a network policy.
  • Destructive command blocking: Commands like rm or git reset --hard are blocked before they run.
Only bash tool commands run inside the sandbox. File tools, MCP servers, custom tools, plugins and !`command` placeholders in custom commands still run on your machine, and changes to your project folder are real changes. Keep using tool permissions alongside the sandbox.

​
Requirements

  1. sbx CLI: The standalone Docker Sandboxes CLI (version 0.26.0 or later). Docker Desktop is not required: sbx runs its own daemon. If sbx is missing, Symbiotic Code offers to install it for you with brew install docker/tap/sbx on macOS or winget install Docker.sbx on Windows. On Linux, install it manually.
  2. Docker account: sbx requires you to sign in with a Docker account. If you aren’t signed in, Symbiotic Code offers to run sbx login, which opens a browser to authenticate.

​
Setup & Activation

Agent sandboxing can be configured at two levels:
  • Organization level: Administrators define a security policy in the Symbiotic Security platform. They can force a setting (it shows as Locked by org) or restrict the values you can choose.
  • Local level: Developers change the settings that aren’t locked with the /agents-security command. Local preferences are stored in ~/.local/share/symbiotic/user-prefs.json.
The sandbox starts in the background when Symbiotic Code launches. The first sandbox creation can take a while: you see a “Waiting for sbx to start…” notification if the agent runs a command before it’s ready. A sandbox is reused for the same project across sessions.
If sbx can’t start (not installed, not signed in, daemon unavailable), shell commands are blocked rather than run on your machine, unless Fallback to host is enabled. If you decline the install or sign-in suggestion and your organization doesn’t make the sandbox mandatory, commands run on your machine instead and you aren’t asked again until the policy changes.

​
Security Parameters

These parameters can be set with the /agents-security command, or enforced by the organization policy:

​
Network policies

Control what outbound connections shell commands can make from inside the sandbox: By default, private and link-local IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16) are blocked, and api.github.com and registry.npmjs.org are allowed. Admins can add organization-wide allowlists and blocklists of hosts and IP ranges (e.g., to prevent data exfiltration to unauthorized endpoints). A blocked host takes precedence over an allowed one. Shell commands that explicitly target a host blocked by your organization (for example curl https://blocked.example.com) are refused before they run.
Network policies are global to sbx on your machine: Symbiotic Code resets and reapplies them each time it starts a sandbox, which overwrites policies you set manually with sbx policy. If the policy can’t be applied, the sandbox is not used and shell commands are blocked.

​
Command guardrails

Prevent the execution of destructive or unsafe commands.
  • Destructive command blocking: When enabled, Symbiotic Code blocks these commands before they run: rm, rmdir, unlink, shred, truncate, mkfs, dd … of=, chmod 777, git reset --hard, git clean -f, git checkout . and redirections to block devices. The agent is told to use a safer alternative or ask you to run the command yourself. This check also applies when commands fall back to running on your machine.
  • Organization blocklist: Admins can block specific programs by name (for example curl or ssh). The agent is told the command is restricted by your organization.

​
Worktree isolation

Worktree isolation keeps the agent’s changes off your current branch.
  • How it works: In a git repository, the sandbox is created on a new branch named after your current branch (<branch>-agent1, <branch>-agent2, …), using a git worktree stored in a .sbx/ folder of your project. Add .sbx/ to your .gitignore.
  • Reviewing work: Inspect the agent’s branch with regular git commands, then run /sandbox-merge to merge it into the branch it was created from.
  • If the project isn’t a git repository, or if your sbx version doesn’t support branches, the project folder is mounted directly and the agent works on your current branch.

​
Sandbox commands

/sandbox-pick, /sandbox-merge and /sandbox-delete are only available when worktree isolation is on. Stopped sandboxes are never deleted automatically, so that you don’t lose the agent’s branch: use /sandbox-delete to clean them up.

​
Technical Details

For more details on how the underlying sandboxing technology operates, refer to the Official Docker Sandboxes Documentation.