OpenCode Docker

A security-hardened Docker environment for running the OpenCode CLI in complete isolation. Features a read-only container with dropped Linux capabilities (principle of least privilege), seccomp profile preventing privilege escalation, and file-based secrets management.

Star History

Getting Started

Prerequisites

• Docker installed on your machine.
• Make
• curl and jq (required for make build-latest)

Quick Start

# Build the image
make build

# Set up your secrets (one-time)
mkdir -p ~/.opencode-docker/secrets
echo "your-api-key" > ~/.opencode-docker/secrets/context7_api_key
chmod 600 ~/.opencode-docker/secrets/*

# Run using the wrapper script (recommended)
bin/opencode-docker

Recommended: Using the Wrapper Script

The bin/opencode-docker script is the recommended way to run OpenCode Docker. It:

• Persists all data to ~/.opencode-docker/ (sessions, cache, settings)
• Reads secrets from ~/.opencode-docker/secrets/
• Uses the current directory as the workspace
• Works from any directory once added to your PATH

Adding to PATH

Bash

Add to your ~/.bashrc:

export PATH="$HOME/git/opencode-docker/bin:$PATH"

Then reload:

source ~/.bashrc

Fish

Run the following command to add opencode-docker to your path. Replace the Path with the correct path for your environment.

fish_add_path $HOME/git/opencode-docker/bin

Usage

Once added to your PATH, you can run from any directory:

# Run in current directory
opencode-docker

# Continue a session
opencode-docker -s ses_2d068fdfaffefxNTts5doK0upT

# Override workspace directory
OPENCODE_WORKSPACE=/path/to/project opencode-docker

Security Features

This container implements defense-in-depth with multiple security layers:

• Complete isolation: Distroless base image with no shell or package manager
• Read-only filesystem: Root filesystem is immutable; only /tmp (tmpfs) and mounted volumes are writable
• Dropped capabilities: --cap-drop ALL removes all Linux capabilities (principle of least privilege)
• Privilege escalation prevention: --security-opt no-new-privileges blocks setuid/setgid exploits
• Unprivileged user: Runs as non-root UID 1000 (configurable at build time)
• Resource limits: Memory (2GB) and CPU (2 cores) constraints prevent resource exhaustion
• File-based secrets: Secrets loaded from files (not environment variables) to avoid exposure in process listings or logs

Secrets Management

This project uses file-based secrets instead of environment variables for improved security. Secrets stored in files are not visible in docker inspect, process listings, error messages, or logs.

Setting Up Secrets

1. Create your secrets directory:

   mkdir -p ~/.opencode-docker/secrets
   chmod 700 ~/.opencode-docker/secrets
   

2. Add your API keys as individual files:

   echo "your-api-key" > ~/.opencode-docker/secrets/anthropic_api_key
   echo "your-api-key" > ~/.opencode-docker/secrets/openai_api_key
   echo "your-api-key" > ~/.opencode-docker/secrets/context7_api_key
   chmod 600 ~/.opencode-docker/secrets/*
   

3. The runtime bootstrap (bootstrap.py) automatically loads all files from /run/secrets as environment variables:

   • Filenames are converted to uppercase
   • Dashes and dots are replaced with underscores
   • Example: anthropic_api_key becomes ANTHROPIC_API_KEY

Supported Secrets

Note: Environment variables can still be passed directly if needed, but file-based secrets are strongly recommended for security.

Data Persistence & Configuration

When using the wrapper script (bin/opencode-docker):

When using make run (development only):

Superpowers Visual Companion

The Superpowers plugin includes a visual brainstorming companion that serves mockups, diagrams, and design options in your browser.

To enable the brainstorming server, use the -b or --brainstorm flag when running bin/opencode-docker. The port is randomly assigned in the range 49152-65535 and will be displayed when the brainstorming skill starts. Access it at the URL shown (e.g., http://localhost:XXXXX).

For development with make run or make shell, the port is pre-configured to 42000 via the BRAINSTORM_PORT environment variable.

Advanced Usage

Development Commands

make build                      # Build with auto-detected UID/GID
make build VERSION=1.3.17       # Build with specific version tag
make build-latest               # Build latest OpenCode version
make tag-latest VERSION=1.3.17  # Tag a version as latest
make run                        # Dev run (uses ./homebase, ./workspace, ./secrets)
make shell                      # Debug shell (builder-tools stage with bash)
make clean                      # Remove image

Manual Docker Run

For advanced users who need custom container configuration:

docker run --rm -it \
  --read-only \
  --tmpfs /tmp:exec,size=512m \
  --cap-drop ALL \
  --security-opt=no-new-privileges \
  --memory=2g \
  --cpus=2 \
  -v ~/.opencode-docker:/app:rw \
  -v /path/to/opencode-docker/config:/app/.config/opencode:rw \
  -v $(pwd):/workspace:rw \
  -v ~/.opencode-docker/secrets:/run/secrets:ro \
  opencode-docker /workspace

Building Manually

# Default UID/GID (1000)
docker build -t opencode-docker .

# With custom UID/GID (recommended)
docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t opencode-docker .

# With version tag
docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t opencode-docker:1.3.17 .

Runtime Details

The image uses a multi-stage build with distroless runtime:

• Base: gcr.io/distroless/base-debian12 (no shell, no package manager)
• Node.js: Node 24 from NodeSource, runtime dependencies extracted via collect-runtime-deps.sh
• Python: Python 3 with venv support from Debian 12
• OpenCode: Installed via official installer in build stage
• Bootstrap: bootstrap.py loads secrets from /run/secrets, starts Xvfb, then execs OpenCode