Opencode Sandbox

OpenCode Sandbox

Run OpenCode inside a luongnv89/docker-dev container for a local project. A fresh local OpenCode profile is used by default: the host's ~/.config/opencode is not mounted. Pass --with-opencode-config only when the task must reuse the host profile or credentials. SSH and GitHub auth remain on by default (~/.ssh, ~/.config/gh, GH_TOKEN from gh auth token) so git commit, git push, gh pr create, and gh pr merge work in the container. Pass --no-ssh --no-github when the task must not reach GitHub. Details: references/mounts-and-credentials.md.

Keep-by-default: the container stays running after the task so the user can attach a shell. Do not remove it unless they confirm (or they asked for --rm up front).

When to Use

• Run OpenCode against a project and let it commit, push, open, or merge a PR (gh / SSH available inside the container)
• OpenCode keeps hitting provider rate limits and the task needs a fresh local profile (a new container with the default mounts, or --fresh-profile)
• The task must not touch GitHub — pass --no-ssh --no-github and review the host diff; push stays a separate step

Repo Sync Before Edits (mandatory)

The container only sees whatever is on disk at docker run time — sync the host repo before launching, not after:

branch="$(git -C "$PROJECT_DIR" rev-parse --abbrev-ref HEAD)"
git -C "$PROJECT_DIR" fetch origin && git -C "$PROJECT_DIR" pull --rebase origin "$branch"

If the tree is dirty: stash (-u), sync, pop. If origin is missing or the rebase conflicts, stop and ask the user before continuing.

Skip this step when the task is read-only inspect (list files, summarize) and will not write the tree. Always sync when the container will edit files.

Choose a mode

Default to one-shot — it needs no pane-management skill, has no TUI-timing gotchas, and its completion signal is a plain process exit code. Reach for interactive mode only when the task genuinely needs a human in the loop mid-run.

One-shot mode

scripts/run_opencode.sh starts a named container (sleep infinity as PID 1 so it stays running), prints an attach command, then runs opencode2 run --auto via docker exec (opencode is used as a fallback for older images). One exit code from OpenCode, output on stdout — no polling, no TUI, no permission dialogs to click through (--auto handles them; see references/mounts-and-credentials.md → Why --auto is required).

The container is kept by default. Do not pass --rm unless the user already asked to throw the container away. After the run, ask them before any docker rm (Step 4).

Step 1 — Decide mounts

Every run mounts the project directory (/workspace). On by default: ~/.ssh, GitHub auth (~/.config/gh + GH_TOKEN), and ~/.gitconfig. The host's ~/.config/opencode is not mounted unless --with-opencode-config is passed. Opt out when the user asks to isolate, or the task must not reach GitHub:

• --no-ssh — do not mount ~/.ssh
• --no-github — do not mount ~/.config/gh or inject GH_TOKEN
• --no-git-identity — do not mount ~/.gitconfig
• --with-opencode-config — mount the host's ~/.config/opencode profile and credentials. This is opt-in; the default is a fresh local profile.
• --fresh-profile — explicitly select a fresh local OpenCode profile (alias for --no-opencode-config). A new profile does not reset provider, model, network, or service rate limits. Anonymous/free models may work without login; authenticate only when needed. Combined with --with-agents, the script also mounts ~/.config/opencode/skills read-only so its relative skill symlinks still resolve — and nothing else from that directory, including service.json. See references/mounts-and-credentials.md.

Add flags only for extras the task needs:

• --with-claude-skills — task must read/follow a user-level Claude Code skill living under ~/.claude/skills/ (mounts ~/.claude and ~/.agents, read-only — see the symlink gotcha in references/mounts-and-credentials.md before assuming one mount is enough). Skip this flag for a project-local skill/convention doc (e.g. AGENTS.md, .claude/skills/ inside the repo itself, a CONTRIBUTING.md) — it's already inside /workspace via the project mount, no extra flag needed.
• --with-agents — mount ~/.agents read-only without ~/.claude. Use when the task needs the skill library but the container should not see Claude Code's own directory.

OpenCode has no native "skill" concept — mounting a directory only makes a file readable, not followed. When using --with-claude-skills, the --message must explicitly point OpenCode at it, e.g.: "Read /root/.claude/skills/<name>/SKILL.md and follow it as your playbook for this task."

Additional options accepted by run_opencode.sh: --with-opencode-config to opt in to mounting the host OpenCode profile; --fresh-profile or --no-opencode-config to explicitly select a fresh local profile; --image IMAGE to override the default container image (ghcr.io/luongnv89/devbox:latest); --format FORMAT to set opencode2 run's output format (default or json; default: default); --name NAME to set the container name (default: opencode-sandbox-<project>-<epoch>); --start-only to create the container and print the attach command without running OpenCode; --exec-in NAME to run OpenCode in an already-started container; --rm to auto-remove the container after OpenCode exits (opt-in — not the default).

Step 2 — Start the container, show attach, then run OpenCode

Invoke the bundled script by absolute path — scripts/run_opencode.sh next to this SKILL.md. Do not run scripts/run_opencode.sh from the project directory; that file is not there.

Two invocations, so the user sees the attach command before OpenCode blocks (a single --project + --message call also works, but the attach line then sits in tool logs until OpenCode exits):

# 2a — create the keep-alive container, print attach, return immediately
bash /path/to/opencode-sandbox/scripts/run_opencode.sh \
  --project /path/to/project \
  --start-only \
  [--with-claude-skills] [--no-ssh] [--no-github]

Parse CONTAINER_NAME=... from stderr. Surface this to the user as a fenced code block now, before step 2b:

docker exec -it <CONTAINER_NAME> zsh

# 2b — run OpenCode inside that container
bash /path/to/opencode-sandbox/scripts/run_opencode.sh \
  --project /path/to/project \
  --message "<task text>" \
  --exec-in "<CONTAINER_NAME>" \
  [--with-claude-skills] [--no-ssh] [--no-github]

For task text too long or complex for a shell argument, write it to a file and attach it on 2b:

bash /path/to/opencode-sandbox/scripts/run_opencode.sh \
  --project /path/to/project \
  --message "Follow the attached file's instructions exactly." \
  --file /path/to/task.txt \
  --exec-in "<CONTAINER_NAME>"

If --exec-in names a container that exists but is stopped, the script runs docker start then execs. If the name does not exist, it errors — do not docker rm a collision to "fix" it unless the user confirms.

preflight.sh (called automatically) checks the Docker daemon is running — starting it on macOS if not — and pulls the image on first use. Both scripts print a specific error with a fix on failure; read the message before retrying blind. Common failures and fixes: references/troubleshooting.md.

Completion criterion for this step: step 2a exited 0 with a CONTAINER_NAME= line; the attach command was shown to the user as a fenced block before step 2b started; step 2b's OpenCode transcript then ran.

Step 3 — Verify before anything ships

Completion criterion: exit code 0 from the --exec-in invocation, and the printed transcript shows the task actually finished (not a mid-task rate-limit retry loop — see references/troubleshooting.md if it stalls). Exit 0 means OpenCode finished without error; the container is still running unless --rm was passed. It does not mean the change is correct or safe to push.

Before treating the run as done:

1. git -C "$PROJECT_DIR" status --short and git -C "$PROJECT_DIR" diff — review every changed file, not just the ones the task description mentioned. A broad git add <dir>/ stages backup/build artifacts (.bak, .orig, stray build output) just as readily as real changes — see references/troubleshooting.md.
2. If the task touched dependency files (package.json, lockfiles, etc.), diff them specifically for container-architecture leakage — a Linux binary promoted into a real (non-optional) dependency has shipped from this exact setup before. See references/troubleshooting.md.
3. Default credentials mean the container can git push / gh pr. Review git status/diff (and the GitHub result) anyway. If the user asked to isolate, you passed --no-ssh --no-github and push stays a separate host step.

Step 4 — Ask before removing the container

Default is keep. Do not run docker rm (or pass --rm) unless the user confirms they want the container gone.

After Step 3, ask once, naming the container:

Container <CONTAINER_NAME> is still running. Attach with docker exec -it <CONTAINER_NAME> zsh. Remove it for cleanup?

• Yes → docker rm -f "$CONTAINER_NAME", then confirm docker container inspect "$CONTAINER_NAME" fails.
• No / no answer → leave it running. Repeat the attach command so they still have a copy-paste line.
• --rm was already passed → the script removed it on exit; skip this step.

Do not treat leftover containers as a failure of the OpenCode task.

Interactive mode

For watching OpenCode work live or steering it mid-task. Needs a real pane/terminal the agent can repeatedly read and write — pair this skill with herdr-agent or tmux-agent-comms for the pane mechanics. Read references/interactive-mode.md for what's specific to OpenCode-in-a-container on top of those primitives: TUI readiness timing (sending too early drops the message, or worse, a second premature send exits OpenCode entirely), permission-dialog handling, and completion detection (container processes are invisible to host-level agent-status tracking — poll the transcript or use a sentinel string instead).

Example

bash ~/.claude/skills/opencode-sandbox/scripts/run_opencode.sh \
  --project ~/code/my-app \
  --start-only
# → show the printed docker exec -it <name> zsh block to the user, then:
bash ~/.claude/skills/opencode-sandbox/scripts/run_opencode.sh \
  --project ~/code/my-app \
  --message "Add input validation to the signup form and run the test suite." \
  --exec-in "<CONTAINER_NAME>"

Expected output: 2a reports Docker/image ready and prints CONTAINER_NAME= plus a copy-paste docker exec -it <name> zsh block, then returns. The user can paste that into another terminal immediately. 2b streams OpenCode's task transcript and exits 0. The container is still running. Back on the host, git -C ~/code/my-app diff shows the validation change and its test — nothing else. Then ask the user whether to docker rm -f <name>. If the transcript instead shows a rate-limit retry loop, treat the run as unfinished (see references/troubleshooting.md), not as a pass.

Acceptance Criteria

• run_opencode.sh exits 0, and the transcript shows the task actually completed (not a stalled rate-limit retry)
• A copy-paste attach command (docker exec -it <container-name> zsh) was shown to the user
• The container was not removed unless the user confirmed cleanup (or they requested --rm up front)
• git -C "$PROJECT_DIR" status --short and git -C "$PROJECT_DIR" diff were reviewed on the host before anything is committed or pushed
• SSH (~/.ssh) and GitHub auth (GH_TOKEN / ~/.config/gh) were mounted unless the user asked to isolate (--no-ssh --no-github)
• Host OpenCode config was not mounted unless --with-opencode-config was explicitly requested
• Dependency-file diffs (package.json, lockfiles) were checked for container-only binaries before treating the run as safe to merge

Edge cases this skill accounts for: a dirty host repo before sync (stash -u, sync, pop); an already-running container from a prior task (name collision — see references/troubleshooting.md); a leftover kept container the user declined to remove (leave it; do not docker rm on your own); a TUI message sent before the interactive pane finishes booting, which drops the message or exits OpenCode entirely (see references/interactive-mode.md).

Step Completion Report

◆ OpenCode Sandbox (one-shot run)
··································································
  Docker daemon:         √ pass (docker info)
  Image ready:           √ pass (ghcr.io/luongnv89/devbox:latest)
  OpenCode CLI:          √ opencode2 (fallback: opencode)
  Profile:               √ fresh by default | √ host profile when requested
  Mounts:                √ workspace, host opencode config when requested, ssh, gh, gitconfig [+ claude skills]
  Credentials:           √ ssh+gh on | √ --no-ssh --no-github (isolated)
  Attach command:        √ docker exec -it <name> zsh shown
  Task exit code:        √ 0 | × <N> — <error from output>
  Host diff reviewed:    √ pass (git status/diff checked) | — n/a (no changes)
  Container:             √ kept (<name>) | √ removed (user confirmed) | √ --rm
  ____________________________
  Result:               PASS | FAIL

Adapt for interactive mode: replace Task exit code with Sentinel/transcript completion and add Permission dialogs handled if any appeared. Container is still kept-until-confirmed unless the user asked to auto-remove.