# 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
   exec sbx run -t localhost/opencode-v2:local "$@" opencode
   ```

   `-t localhost/opencode-v2:local` points at the template `make build`
   registers (see below); `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`.