opencodev2

Config and make utilities for running OpenCode v2 inside a Docker Sandbox — an isolated environment that mounts your working directory read-write, limits network access by policy, and keeps agent-installed tooling out of your host machine.

Prerequisites

1. Install the sbx CLI (one-time, on your host):

   # macOS
   brew trust docker/tap
   brew install docker/tap/sbx
   
   # Ubuntu (with Docker Engine already installed)
   curl -fsSL https://get.docker.com | sudo SBX=1 sh
   
   # Windows
   winget install -h Docker.sbx
   

   See docs.docker.com/ai/sandboxes/install for other platforms and system-wide installs.

2. Authenticate and store a credential for whichever model provider OpenCode should use (one-time, host-level secrets — not stored in this repo):

   sbx login
   sbx secret set anthropic   # or: openai, google, openrouter, ...
   sbx secret set github      # optional, for repo/PR access via `gh auth token`
   

Quick start

make build                 # build the image, register it with sbx as a local template
make install                # install the opencode-sandbox shim (one-time)
. ~/.bashrc                 # or ~/.zshrc / restart your shell — whatever install.sh edited

cd ~/some-project
opencode-sandbox             # launch OpenCode v2 in a sandbox, workspace = current directory

opencode-sandbox works from any directory once installed — it's not tied to this project directory, and it's not named opencode so it won't shadow a real, locally-installed OpenCode CLI on your PATH. Re-run make build whenever you bump OPENCODE_VERSION or change ./Dockerfile; make install only needs to run once per machine.

On first run, sbx asks you to pick a global network policy (Open / Balanced / Locked Down). Balanced is a reasonable default. Adjust anytime:

sbx policy ls                      # show current rules
sbx policy allow network <host>    # allow an extra host

What make install does

install.sh is POSIX /bin/sh (not shell-specific) and does two things, both idempotent — safe to re-run:

1. Writes a shim to ~/.local/bin/opencode-sandbox:

   #!/bin/sh
   # sbx run accepts -t/--template only at sandbox creation time; re-running
   # against an existing sandbox with a template fails. So pass the template
   # only when the named sandbox doesn't exist yet.
   TEMPLATE=localhost/opencode-v2:local
   
   # Extract --name VALUE / --name=VALUE from the arguments, if given.
   name=
   prev=
   for arg in "$@"; do
     [ "$prev" = --name ] && name=$arg
     case "$arg" in
       --name=*) name=${arg#--name=} ;;
     esac
     prev=$arg
   done
   
   if [ -n "$name" ] && sbx ls -q 2>/dev/null | grep -Fxq -- "$name"; then
     exec sbx run "$@" opencode
   fi
   
   exec sbx run -t "$TEMPLATE" "$@" opencode
   

   -t localhost/opencode-v2:local points at the template make build registers (see below), passed only when --name names a sandbox that doesn't exist yet (sbx rejects a template when re-attaching); opencode is the agent name; "$@" forwards any extra args (e.g. opencode-sandbox --model claude-sonnet-5). Being a real executable on PATH rather than a shell function means it works identically under bash, zsh, fish, or anything else.

2. If ~/.local/bin isn't already on PATH, adds it — detecting your login shell via $SHELL (not whatever shell happens to run this script) and picking the right config file: ~/.zshrc for zsh (falling back to an existing ~/.zshenv if that's what you already use), ~/.bash_profile on macOS / ~/.bashrc elsewhere for bash, fish_add_path for fish (no file to edit), or ~/.profile otherwise.

This pattern (shim binary + per-shell/per-OS config detection + marker-based idempotent edit) is adapted from install-shortcut.sh in a related project.

Running OpenCode v2 (not the built-in v1 template)

sbx run opencode on its own uses Docker's stock image, docker/sandbox-templates:opencode, which bakes in OpenCode v1 — the opencode-ai npm package, pinned at 1.18.32 as of this writing (verified with docker run --rm --entrypoint sh docker/sandbox-templates:opencode -c 'opencode --version').

OpenCode v2 is real and actively published, but as a different npm package: @opencode/cli (currently 2.0.26 — verify with npm view @opencode/cli version). The old opencode-ai line never became v2; it was superseded by this new package, which is why checking opencode-ai's version history makes v2 look like it doesn't exist. Both packages install a binary named opencode into the same global npm prefix, so getting v2 means removing the v1 package first, then installing the v2 one — confirmed by actually building this and running opencode --version inside the result, which reports opencode v2.0.26.

./Dockerfile does the swap at the image level:

FROM docker/sandbox-templates:opencode
ARG OPENCODE_VERSION=2.0.26
RUN npm uninstall -g opencode-ai \
    && npm install -g @opencode/cli@${OPENCODE_VERSION}

sbx runs each sandbox in its own isolated microVM with its own Docker daemon/image cache, so a plain docker build on your host is invisible to it — make build closes that gap with docker image save + sbx template load, which registers the image as a local template sbx run -t localhost/... (or sbxenv.yaml's sandboxOptions.template) can find.

To bump to a newer v2 release:

make build OPENCODE_VERSION=2.0.27   # or any other published @opencode/cli version

or edit the OPENCODE_VERSION default in the Makefile. Avoid pinning to latest long-term — once the image layer is cached, Docker won't re-resolve latest on later builds, so it'll silently stop tracking new releases; use --no-cache or bump to an explicit version instead.

Note: sbxenv.yaml's sandboxOptions.template is currently set to the bare tag opencode-v2:local, while the opencode-sandbox shim above (and sbx template load's own output) use the localhost/opencode-v2:local form. If running sbx run opencode from inside this directory (reading sbxenv.yaml) doesn't find the template, try adding the localhost/ prefix there too.

Makefile targets

make image     build the opencode-v2:local image (OPENCODE_VERSION=2.0.26 by default)
make build     image + register it with sbx as a local template
make install   install the opencode-sandbox shim to ~/.local/bin

Everything else — sbx login, sbx secret set, sbx policy, sbx run, sbx stop/rm/ls, sbx ports — is plain sbx; there's no Makefile wrapper for those.

Notes

• make build is meant to run on your host machine — sbx has no nested sandbox-in-sandbox mode.
• The published CLI reference page is JS-rendered and didn't fully resolve during research for this README; if a command here doesn't match your installed sbx version, check sbx <command> --help.