opencode-sandbox

An OpenCode plugin that autoprovisions isolated sandbox environments for AI agents. Supports multiple providers with automatic detection and seamless fallback.

How it works

When you start a chat in OpenCode, the plugin creates an isolated container/sandbox and syncs your project files into it. The agent's file and shell tools then execute inside the sandbox instead of on your host machine. Changes are synced back via git on idle.

• Secrets stay on the host — .gitignore is respected during file transfer, so .env files and other ignored content never reach the sandbox.
• Path translation is transparent — the agent sees host paths but operations happen at /workspace inside the sandbox.
• Sandboxes are ephemeral — created per session, cleaned up when the session ends.

Providers

Provider	SDK	Trigger	Notes
Daytona	@daytonaio/sdk	DAYTONA_API_KEY	Native SSH sync, preview URLs
E2B	@e2b/code-interpreter	E2B_API_KEY	Cloud sandboxes, preview URLs via {port}-{id}.e2b.app
Sprites	@fly/sprites	SPRITES_TOKEN	Fly.io-based, REST filesystem API
Docker	(none)	Fallback	Local containers, works with Podman via podman-docker

Auto-detection priority: SANDBOX_PROVIDER env var > DAYTONA_API_KEY > E2B_API_KEY > SPRITES_TOKEN > Docker fallback.

To force a specific provider, set SANDBOX_PROVIDER=daytona|e2b|sprites|docker.

Installation

The plugin lives in .opencode/plugin/ and is auto-discovered by OpenCode (no build step — Bun loads .ts directly).

1. Clone this repo into your project or as a standalone project:

   git clone https://github.com/rswift/opencode-sandbox.git

2. Install runtime dependencies (used by Bun at load time):

   cd .opencode && bun install

3. Install dev dependencies (for type-checking only):

   npm install

4. Set provider credentials (or just use Docker as the fallback):

   # Pick one:
   export DAYTONA_API_KEY="..."
   export E2B_API_KEY="..."
   export SPRITES_TOKEN="..."
   # Or set nothing — Docker/Podman is the default

Docker provider on Fedora / Podman

If you're using Podman, install the Docker CLI compatibility layer:

sudo dnf install podman-docker

The Docker provider also accepts a custom image via SANDBOX_DOCKER_IMAGE:

export SANDBOX_DOCKER_IMAGE="node:20"  # default: ubuntu:22.04

Configuration

Environment Variable	Description
SANDBOX_PROVIDER	Force a specific provider (daytona, e2b, sprites, docker)
DAYTONA_API_KEY	Daytona API key
DAYTONA_SERVER_URL	Daytona server URL
DAYTONA_TARGET	Daytona target name
E2B_API_KEY	E2B API key
SPRITES_TOKEN	Sprites (Fly.io) token
SANDBOX_DOCKER_IMAGE	Docker image to use (default: ubuntu:22.04)

Tools provided

The plugin replaces OpenCode's built-in file/shell tools with sandbox-aware versions:

Tool	Description
bash	Execute shell commands inside the sandbox
read	Read file contents
write	Write/create files
edit	Single edit (find & replace)
multiedit	Multiple edits in one file
ls	List directory contents
glob	Find files by pattern
grep	Search file contents
getPreviewURL	Get a URL for a running service port

Project structure

.opencode/
├── package.json              # Bun runtime dependencies
└── plugin/
    ├── index.ts              # Plugin entry point
    └── sandbox/
        ├── index.ts          # Orchestrator
        ├── core/             # Session manager, logger, toast, types
        ├── providers/        # Provider adapters (daytona, e2b, sprites, docker)
        ├── git/              # Git sync (host, sandbox, session managers)
        ├── plugins/          # Sub-plugins (cleanup, idle-commit, system-transform)
        └── tools/            # Sandbox-aware tool implementations
package.json                  # Dev dependencies (tsc type-checking)
tsconfig.json                 # Base TypeScript config
tsconfig.lib.json             # Build config
test-docker.ts                # Docker provider integration tests

Development

# Type-check (no emit)
npm run type-check

# Build to dist/
npm run build

# Run Docker provider tests (requires Docker or Podman)
npx tsx test-docker.ts

License

Apache-2.0