179 lines
7.2 KiB
Markdown
179 lines
7.2 KiB
Markdown
# opencodev2
|
|
|
|
Config and `make` utilities for running **OpenCode v2** inside a
|
|
[Docker Sandbox](https://docs.docker.com/ai/sandboxes/) — 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):
|
|
|
|
```console
|
|
# 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](https://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):
|
|
|
|
```console
|
|
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
|
|
|
|
```console
|
|
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`](./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:
|
|
|
|
```console
|
|
sbx policy ls # show current rules
|
|
sbx policy allow network <host> # allow an extra host
|
|
```
|
|
|
|
## What `make install` does
|
|
|
|
[`install.sh`](./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`:
|
|
|
|
```sh
|
|
#!/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`](https://cloud.inputobjects.eu/forge/jrozanski/opencode-sandbox/src/branch/main/scripts/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`](./Dockerfile) does the swap at the image level:
|
|
|
|
```dockerfile
|
|
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:
|
|
|
|
```console
|
|
make build OPENCODE_VERSION=2.0.27 # or any other published @opencode/cli version
|
|
```
|
|
|
|
or edit the `OPENCODE_VERSION` default in the [`Makefile`](./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`](./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
|
|
|
|
```console
|
|
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](https://docs.docker.com/reference/cli/sbx/) 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`.
|