devsnowdon/opencode-docker repository overview

⁠opencode dev container

Version	Empty	Duck	Full
v2
v1

OpenCode doesn’t impose an opinion on the sandbox its agents run in. A sandboxed launcher gives you a secure, controlled environment that still lets agents work with the permissions they need.

Snowdon Dev's opencode-docker is a security- and human-control-oriented OpenCode⁠ workflow that runs inside Docker containers. It lets you manage multiple agents, including sub-agents, across distinct worktrees of your repository library, all through a simple CLI. Your project is available in the container at /workspace/project, and toolchain caches (Go, Rust, Node.js, Python) persist between runs.

Every feature is security-first, and convenience features are opt-in. Built for arm devices like the Raspberry Pi⁠ but compatible with x86 and others — please report any issues you find. The opencode version is updated weekly, best-effort; file an issue if yours is out of date. See Build⁠.

⁠Commands

⁠Examples

# a workspace argument overrides the current directory
opencode /home/other/somerepo
opencode:exec /home/other/somerepo sh
opencode:down /home/other/somerepo
opencode:delete "$(pwd)" --all
opencode:ls --quiet ~/somerepo
opencode:compose exec -it opencode sh

# long tasks, then work in the same container
opencode:run npm install
opencode:setup sh -c 'cd front-end && npm install' && opencode

# tasks, replacing the session or analysing the branch first
opencode -c --auto
opencode:changes "identify issues in these changes"
opencode:bg ./ "refactor this module"

# plan with the workspace read-only (only --output is writable), then run the
# plan with bg; changes --output plans the branch changes the same way
opencode:changes --output /tmp/plan.md
opencode:io --output /tmp/out.md < /tmp/create-task-plan.md
opencode:bg ./ < /tmp/out.md

# new projects, either with a real path or under $SD_REPO_HOME
opencode:scaffold /tmp/project < /tmp/sometask.md
opencode:scaffold --path gists/project-1 "Create basic hello world html project"

# workspace assets, and an agent worktree to run in
opencode:create --dockerfile
opencode:create --worktree feature/my-branch
opencode:create --dockerfile --worktree && opencode:uptree

# run on another base image, or pin and cap the CPUs
OPENCODE_IMAGE_URL="devsnowdon/opencode-docker:full-v1" opencode
OPENCODE_CPUSET="2-3" OPENCODE_CPUS="2" opencode

# using opencode v2
OPENCODE_IMAGE_URL="devsnowdon/opencode-docker:empty-v2" \
OPENCODE_IMAGE_URL_TUI="devsnowdon/opencode-docker:empty-v2" opencode

⁠Install

Clone the repository to ~/opencode (the launcher looks for its files there, and a .env in the repository root is read by plain docker compose runs):

git clone https://github.com/snowdon-dev/opencode-docker.git ~/opencode

Only SD_OPENCODE is required; the rest is optional: Compose variables⁠ move toolchain cache paths, Launcher variables⁠ configure the launcher itself.

⁠oh-my-zsh plugin

mkdir -p "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/opencode"
ln -s ~/opencode/omz/opencode.zsh \
    "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/opencode/opencode.plugin.zsh"

export SD_OPENCODE="$HOME/opencode"
export SD_REPO_HOME="$HOME/repos"
plugins=(... opencode)

⁠Environment setup steps

• SD_OPENCODE must point at the repository (default $HOME/opencode).
• Docker is required (docker.io⁠); rootless Docker works for extra security.
• A modern version of bash is required.
• The opencode binary on your shell path runs the TUI (npm i -g opencode-ai); without it an in-container TUI is used instead.
• CPUs are unrestricted by default; limit them with OPENCODE_CPUSET (pinning) or OPENCODE_CPUS (count).
• To apply a custom Dockerfile to every workspace without setting OPENCODE_DOCKERFILE, copy Dockerfile.example to $SD_OPENCODE/Dockerfile.
• It is recommended to use the API key file method⁠ and configure a provider in the project configuration template to read the key from the file. See Config, data and cache directories⁠ below.

⁠config, data and cache directories

opencode's config, data and cache live on the host under three roots — OPENCODE_CONFIG_ROOT (~/.config/opencode-docker), OPENCODE_DATA_ROOT (~/.local/share/opencode-docker) and OPENCODE_CACHE_ROOT (~/.cache/opencode-docker) — with a per-project directory created under each one automatically at launch. Each root must exist, be a directory and be writable; the launcher offers to create what is missing (SD_YOLO=true does it without asking). If your user is not uid/gid 1000, chown -R 1000:1000 the roots instead.

The first launch of a project copies $OPENCODE_CONFIG_ROOT/template into the project's config; later launches leave it alone, so your changes survive. Delete the project's config directory to re-seed it from the template.

A simple root template for opencode v2 could could be (~/.config/opencode-docker/template/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",

  // Default model for all sessions.
  //"model": "opencode/big-pickle",
  //"model": "opencode-go/gpt-5.6-luna",
  //"model": "opencode-go/gpt-6-luna",
  "model": "opencode-go/mimo-v2.6-flash",
  "providers": {
    "opencode-go": {
      "settings": {
        "apiKey": "{file:/var/run/secrets/api_key}"
       }
     }
   },
  "variant": "low",
  "skills": [
    "/opt/opencode/skills"
  ]
}

Set OPENCODE_CONFIG_DIR, OPENCODE_DATA_DIR or OPENCODE_CACHE_DIR to use one exact directory instead of a root. They are launcher variables: export them in the shell, not in a .env file.

Toolchain caches (OPENCODE_PIP_CACHE_DIR, OPENCODE_NPM_CACHE_DIR, OPENCODE_GO_BUILD_CACHE_DIR, OPENCODE_GO_MOD_CACHE_DIR, OPENCODE_CARGO_REGISTRY_DIR, OPENCODE_CARGO_GIT_DIR, OPENCODE_SCCACHE_DIR) are only mounted when enabled with OPENCODE_CACHE; see Compose variables⁠. Create and chown them only if you enable them.

The container also writes to your workspace, so if something fails on permissions make sure it is owned by the container user:

chown -R 1000:1000 "$WORKSPACE"

⁠Environment variables

⁠Compose variables

Toolchain cache and workspace host paths are configured with environment variables; every one has a default under your home directory.

⁠Launcher variables

These variables are read by the launcher from the shell environment:

⁠How a session starts

opencode (the start command) starts a backend inside the container, waits for it to become healthy, then attaches a TUI — your host opencode binary when one is on PATH, otherwise a one-off in-container tui service. The backend is stopped when the TUI exits.

run, changes and setup use the running container when there is one, a throwaway container otherwise; scaffold and bg always use a throwaway one. io (and changes --output) always run on their own, with the workspace mounted read-only (see opencode:help io).

⁠Security model

• Workspace .git directories are mounted read-only, so history cannot be rewritten and commands cannot be injected; SD_READ_ONLY=false opts out.
• opencode:io and opencode:changes --output mount the whole workspace read-only; only the declared --output paths are writable.
• A worktree's parent repository .git is mounted read-only, keeping git usable while the worktree stays isolated.
• Each workspace gets its own Docker network, isolated from other workspaces.
• Toolchain caches and other host mounts are opt-in (OPENCODE_CACHE).
• The api key travels as a file, never an environment variable.
• A workspace outside $HOME prompts before it is used, unless SD_YOLO=true.

⁠API key secret

Put your api key in OPENCODE_KEY_FILE (default ~/.config/opencode-docker/opencode.key); a non-empty file is mounted into the container at /run/secrets/api_key and stays out of the container's environment, docker inspect and docker compose config. When the file is missing or empty the backend starts without a key. The container user must be able to read the file.

opencode reads the key from that path only when your config says so: add the reference to the provider in the opencode.json of your config template ($OPENCODE_CONFIG_ROOT/template, see config, data and cache directories⁠). On the v2 images it goes into providers.<id>.settings.apiKey:

{
    "providers": {
        "opencode-go": {
            "settings": {
                "apiKey": "{file:/run/secrets/api_key}"
            }
        }
    }
}

On the v1 images the same {file:/run/secrets/api_key} reference goes into provider.<id>.options.apiKey instead.

⁠Network isolation

OPENCODE_NETWORK picks one of three modes:

1. Unset (default) — Docker's default bridge network.
2. @default (recommended) — a bridge network created for this workspace on first use and reused across restarts; clean up with opencode:delete --all.
3. Named network — any existing Docker network, shared between workspaces or external services.

OPENCODE_NETWORK=@default opencode
OPENCODE_NETWORK="my-shared-net" opencode

Each workspace network gets its own subnet, carved from OPENCODE_NET_RANGE (default 172.20.0.0/16) at OPENCODE_NET_SUBNET (default /29).

⁠Setting variables

Launcher variables are read from the shell environment, not from a .env file. Compose variables resolve in this order: shell environment, a .env file next to the compose files (~/opencode/.env), then the defaults in docker-compose.yml.

opencode:env (ocenv) prints the exported SD_* and OPENCODE_* variables the launcher sees — useful for checking a shell profile before launching anything. Only exported variables appear:

opencode:env | grep '^SD_'
opencode:env | grep '^OPENCODE_CACHE'

opencode:env ws prints the effective workspace path.

⁠Env file example

Add a file like the following to ~/opencode/.env (only the toolchain cache paths you want to move; every other path variable keeps its default):

OPENCODE_PIP_CACHE_DIR=/mnt/usb2/storage/opencode/cache/pip
OPENCODE_SCCACHE_DIR=/mnt/usb2/storage/opencode/cache/rust/sccache

The launcher-managed roots are launcher variables and belong in the shell environment instead — a .env file never reaches the launcher:

export OPENCODE_CONFIG_ROOT=/mnt/usb2/storage/opencode/config
export OPENCODE_DATA_ROOT=/mnt/usb2/storage/opencode/data
export OP