OpenCode Sandbox

An all-in-one, Docker-based sandboxed environment for running OpenCode with additional development tools and MCP servers pre-installed.

Features

• OpenCode — AI-powered coding agent
• agent-browser — Browser automation via Playwright
• Engram — Persistent memory MCP server
• codebase-memory-mcp — Codebase knowledge graph
• openspec-mcp — Specification-driven development
• Prettier, Biome, Ruff, Stylelint — Linters and formatters
• ShellCheck, yamllint — Shell and YAML linting

Architecture

The OpenCode configuration directory itself, including skills, tools, and agents, is mounted read-only.

# Enforce the configuration location
OPENCODE_CONFIG_DIR=/home/node/.config/opencode

# Map the original OpenCode config directory as read-only
~/.config/opencode:/home/node/.config/opencode:ro

# If it exists, the authentication file will also be mapped read-only
~/.local/share/opencode/auth.json:/home/node/.local/share/opencode/auth.json:ro

The project directory where opencode-sandbox is started, is mounted as read-write project root.

Project-specific files like prompts and sessions are stored within the project directory itself, under the .memory directory. This allows you to store and resume sessions while still having a sandboxed environment.

$(PROJECT_ROOT)/.memory/codebase-memory-mcp/:/home/node/codebase-memory-mcp/:rw
$(PROJECT_ROOT)/.memory/engram/:/home/node/.engram/:rw
$(PROJECT_ROOT)/.memory/opencode/prompt-history.jsonl:/home/node/.local/state/opencode/prompt-history.jsonl:rw
$(PROJECT_ROOT)/.memory/opencode/opencode.db:/home/node/.local/share/opencode/opencode.db:rw
$(PROJECT_ROOT)/.memory/opencode/opencode.db-shm:/home/node/.local/share/opencode/opencode.db-shm:rw
$(PROJECT_ROOT)/.memory/opencode/opencode.db-wal:/home/node/.local/share/opencode/opencode.db-wal:rw

MCP servers like engram and Playwright live within the container. Configuration files are mapped read-only, if they exist on the host.

~/.gitconfig:/home/node/.gitconfig:ro
~/.agent-browser/config.json:/home/node/.agent-browser/config.json:ro

Prerequisites

• Docker
• make
• a working OpenCode configuration

Quick Start

# Use the default .env file, adjust where needed
cp env.example .env

# Build the sandbox image
make image

# Run OpenCode in the sandbox
make run

There is also an elevated version, which allows the OpenCode container Docker access. Please note that this is not secure, and would allow (any process within) OpenCode to break out of the sandbox easily.

make run-elevated

This will map the following additional files:

/usr/bin/docker:/usr/bin/docker:ro
/usr/libexec/docker:/usr/libexec/docker:ro
/var/run/docker.sock:/var/run/docker.sock:ro

Configuration

Configuration is managed via a .env file. Copy the example and adjust:

cp env.example .env

Environment Variables

Variable	Default	Description
ENGRAM_VERSION	1.20.0	Version of the Engram binary to download
GROUP	default group	Group name to be used in Docker container
LEMONADE_HOST	(empty)	Hostname for --add-host mapping (set in .env)
HOST_LEMONADE	(empty)	IP address to map LEMONADE_HOST to (for local dev)
TARGET	example.com	Test target hostname for screenshot tests
OPENCODE_SERVER_USERNAME	(current user)	Username for make server
OPENCODE_SERVER_PASSWORD	(current user)	Password for make server

Usage

Build

make image     # Build without preflight checks
make run-tests # Run tests

Run

make run      # Run OpenCode sandbox
make latest   # Run with "latest" tag
make bash     # Start a bash shell in the sandbox
make elevated # Run with Docker socket access
make server   # Run OpenCode server (requires OPENCODE_SERVER_PASSWORD)

Test

make run-tests                # Run all tests inside Docker
make run-tests TYPE=linters   # Run only linter checks
make run-tests TYPE=updates   # Check for package updates
./test.sh [IMAGE_NAME] [TYPE] # Run tests locally

License

This project is licensed under the GNU General Public License v3.0 or later. See LICENSE for details.

Copyright

Copyright (C) 2026 Peter Mosmans