opencode-sandbox

An OpenCode plugin that sandboxes agent-executed commands using @anthropic-ai/sandbox-runtime.

Every bash tool invocation is wrapped with OS-level filesystem and network restrictions — no containers, no VMs, just native OS sandboxing primitives.

Platform	Mechanism
macOS	sandbox-exec (Seatbelt profiles)
Linux	bubblewrap (namespace isolation)
Windows	Not supported (commands pass through)

Install

// opencode.json
{
  "plugin": ["opencode-sandbox"]
}

The plugin is automatically installed from npm when OpenCode starts.

Linux prerequisites

1. Install bubblewrap:

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

2. Ubuntu 24.04+ (AppArmor fix):

Ubuntu 24.04 and later restrict unprivileged user namespaces via AppArmor, which prevents bubblewrap from working. You need to enable the bwrap-userns-restrict AppArmor profile:

# Install the AppArmor profiles package
sudo apt install apparmor-profiles

# Create the symlink to enable the profile
sudo ln -s /etc/apparmor.d/bwrap-userns-restrict /etc/apparmor.d/force-complain/bwrap-userns-restrict

# Load the profile
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

You can verify bwrap works:

bwrap --ro-bind / / --dev /dev --proc /proc -- echo "sandbox works"

Without this fix, bwrap will fail with loopback: Failed RTM_NEWADDR: Operation not permitted or setting up uid map: Permission denied.

What it does

When the agent runs a bash command, the sandbox enforces three layers of protection:

Filesystem write protection

Commands can only write to the project directory and /tmp. Writing anywhere else returns "Read-only file system":

$ touch ~/some-file
touch: cannot touch '/home/user/some-file': Read-only file system

$ echo "data" > /etc/config
/usr/bin/bash: line 1: /etc/config: Read-only file system

Sensitive file read protection

Access to credential directories is blocked:

$ cat ~/.ssh/id_rsa
cat: /home/user/.ssh/id_rsa: Permission denied

Network allowlist

Only approved domains are reachable. All other traffic is blocked via a local proxy:

$ curl https://evil.com
Connection blocked by network allowlist

$ curl https://registry.npmjs.org
(works — npmjs.org is in the default allowlist)

Default restrictions

Filesystem (deny-read):

• ~/.ssh, ~/.gnupg
• ~/.aws/credentials, ~/.config/gcloud
• ~/.npmrc, ~/.env

Filesystem (allow-write):

• Project directory
• Git worktree (validated — unsafe paths like / are rejected)
• /tmp

Network (allow-only):

• registry.npmjs.org, *.npmjs.org
• registry.yarnpkg.com
• pypi.org, crates.io
• github.com, *.github.com
• gitlab.com, *.gitlab.com
• api.openai.com, api.anthropic.com
• *.googleapis.com

Everything else is blocked by default.

Configuration

Option 1: Config file

// .opencode/sandbox.json
{
  "filesystem": {
    "denyRead": ["~/.ssh", "~/.aws/credentials"],
    "allowWrite": [".", "/tmp", "/var/data"],
    "denyWrite": [".env.production"]
  },
  "network": {
    "allowedDomains": [
      "registry.npmjs.org",
      "github.com",
      "*.github.com",
      "api.openai.com",
      "api.anthropic.com",
      "my-internal-api.company.com"
    ],
    "deniedDomains": ["malicious.example.com"]
  }
}

Option 2: Environment variable

OPENCODE_SANDBOX_CONFIG='{"filesystem":{"denyRead":["~/.ssh"]},"network":{"allowedDomains":["github.com"]}}' opencode

Option 3: Disable

OPENCODE_DISABLE_SANDBOX=1 opencode

Or in .opencode/sandbox.json:

{
  "disabled": true
}

How it works

The plugin uses two OpenCode hooks:

1. tool.execute.before — Intercepts bash commands and wraps them with SandboxManager.wrapWithSandbox() before execution
2. tool.execute.after — Restores the original command in the UI (hides the bwrap wrapper)

Agent → bash tool → [plugin wraps command] → sandboxed execution → [plugin restores UI] → Agent

The AI model interprets sandbox errors (like "Read-only file system" or "Connection blocked") directly from command output — no additional annotation layer needed.

Fail-open design

If anything goes wrong (sandbox init fails, wrapping fails, platform unsupported), commands run normally without sandbox. The plugin never breaks your workflow.

Contributing

See CONTRIBUTING.md for development setup, architecture, and guidelines.

Related

• @anthropic-ai/sandbox-runtime — The underlying sandbox engine
• OpenCode Plugins Docs — How to create and use plugins
• Claude Code Sandboxing — Anthropic's sandboxing documentation