Merge pull request #1 from dtump/feature/opencode-container

feat: replace Claude Code with OpenCode

Author: dtump

.github/workflows/ci.yml

@@ -106,26 +106,26 @@ jobs:
           # image. Build is amd64-only (single-arch load is fine); arm64
           # coverage relies on the maintainers' local builds for now.
           load: true
-          tags: claude-docker:ci
+          tags: opencode:ci
           platforms: linux/amd64
           cache-from: type=gha
           cache-to: type=gha,mode=min
 
-      - name: Smoke test — claude --version matches Dockerfile pin
-        # Catches the 2.1.x failure mode where the JS launcher is installed
-        # but the native-binary postinstall isn't run, leaving `claude` as a
+      - name: Smoke test — opencode --version matches Dockerfile pin
+        # Catches the failure mode where the JS launcher is installed
+        # but the native-binary postinstall isn't run, leaving `opencode` as a
         # stub that errors at exec time. Asserts the actual reported version
-        # matches the CLAUDE_CODE_VERSION pin in pins/claude-code.env.
+        # matches the OPENCODE_VERSION pin in pins/opencode.env.
         run: |
           set -euo pipefail
-          EXPECTED=$(python3 update_pins.py --list-npm-tools | awk -F'\t' '$1=="claude-code"{print $5}')
-          ACTUAL=$(docker run --rm claude-docker:ci claude --version)
+          EXPECTED=$(python3 update_pins.py --list-npm-tools | awk -F'\t' '$1=="opencode"{print $5}')
+          ACTUAL=$(docker run --rm opencode:ci opencode --version)
           echo "Expected: ${EXPECTED}  Actual: ${ACTUAL}"
-          [[ "$ACTUAL" == "${EXPECTED} (Claude Code)" ]]
+          [[ "$ACTUAL" == "${EXPECTED}" ]]
 
       - name: Cross-platform smoke (Linux)
         # Drives smoke.sh across a matrix of cells, all reusing the already-loaded
-        # claude-docker:ci image from the build step above.  Do NOT move this to a
+        # opencode:ci image from the build step above.  Do NOT move this to a
         # separate job — a separate job gets a blank local daemon and cannot reuse
         # the image loaded by the build step.
         #
@@ -141,12 +141,12 @@ jobs:
         #   9. runner-uid/ro/no-optins       — read-only workspace (EROFS robustness)
         run: |
           set -euo pipefail
-          export IMAGE=claude-docker:ci
+          export IMAGE=opencode:ci
           RUNNER_UID=$(id -u)
 
           run_cell() {
             echo "--- Cell: $* ---"
-            IMAGE=claude-docker:ci bash smoke/smoke.sh "$@"
+            IMAGE=opencode:ci bash smoke/smoke.sh "$@"
           }
 
           # 1. Baseline: runner UID, cold volume, no opt-ins.

AGENTS.md

@@ -0,0 +1,90 @@
+# OpenCode Agents Configuration
+
+This file documents the OpenCode configuration for the opencode-docker project.
+
+## Project Overview
+
+`opencode-docker` is a hardened Docker wrapper for OpenCode that provides:
+- Isolated workspace access via bind mounts
+- Credential opt-in mechanisms for AWS, GitHub, GitLab, and Terraform Cloud
+- GitHub auth proxy sidecar for secure token handling
+- Private package registry support
+- File ownership preservation (host UID/GID mapping)
+- Security hardening via capability dropping and no-new-privileges
+
+## Agent Configuration
+
+### Primary Agent
+The main OpenCode agent runs inside the container with access to mounted workspaces and opted-in credentials.
+
+### Config Directory
+- **Host:** `~/.config/opencode/`
+- **Container:** `/root/.config/opencode/`
+
+Mounted items from host config:
+- `agents/` - Custom agent definitions
+- `skills/` - Custom skills
+- `commands/` - Slash commands
+- `AGENTS.md` - Global preferences
+- `opencode.docker.json` - Container-specific OpenCode config (copied to `opencode.json`)
+
+### Settings
+Container-specific settings are managed via `opencode.docker.json`, which is copied to `opencode.json` in the container at startup. This allows in-session config changes to persist for the container's lifetime while being re-seeded from the host on each start.
+
+See `examples/opencode.docker.json` for a starting configuration.
+
+## Security Model
+
+### Protected
+- Host filesystem outside passed workspaces
+- Host `~/.aws/credentials` (long-lived keys)
+- Host credential directories (read-only when opted in)
+
+### Exposed (per session, when opted in)
+- Workspace directories (read-write unless `--ro`)
+- Short-lived AWS SSO bearer tokens
+- GitHub tokens (via proxy sidecar or direct forwarding)
+- GitLab tokens
+- Terraform Cloud tokens
+- Private registry configuration files
+
+### Persistent State
+Named volumes carry state across runs (unless `--ephemeral`):
+- `opencode-root` - `/root` (OAuth tokens, shell history)
+- `opencode-home` - `/root/.config/opencode` (conversation history, settings)
+
+## Usage Patterns
+
+### Multi-workspace
+```bash
+opencode-docker ~/repo-a ~/repo-b
+```
+
+### Credential Opt-in
+```bash
+opencode-docker --aws --gh ~/repo
+```
+
+### Read-only Review
+```bash
+opencode-docker --ephemeral --ro ~/untrusted-repo
+```
+
+### Split-pane Teams
+```bash
+opencode-docker --iterm ~/repo  # iTerm2 native panes
+opencode-docker --tmux ~/repo   # Plain tmux splits
+```
+
+## Customization
+
+Extend the base image with project-specific tooling:
+```dockerfile
+FROM opencode:local
+RUN apt-get install -y my-tool
+```
+
+Then use with:
+```bash
+OPENCODE_DOCKER_IMAGE=my-opencode:local opencode-docker ~/repo
+```

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Contributions to `claude-docker` are welcome from anyone.
+Contributions to `opencode-docker` are welcome from anyone.
 
 ## Workflow
 
@@ -29,8 +29,8 @@ hadolint --config .hadolint.yaml Dockerfile
 python3 -m unittest discover -s tests -p 'test_*.py' -v
 
 # Build the image and run a smoke cell against it
-docker build -t claude-code:local .
-IMAGE=claude-code:local bash smoke/smoke.sh --uid="$(id -u)" --optins=aws,glab,tfe
+docker build -t opencode:local .
+IMAGE=opencode:local bash smoke/smoke.sh --uid="$(id -u)" --optins=aws,glab,tfe
 ```
 
 See [`README.md`](README.md) for the full architecture, threat model, and the

Dockerfile

@@ -41,13 +41,13 @@ RUN echo 'APT::Sandbox::User "root";' > /etc/apt/apt.conf.d/10no-sandbox \
 
 # Free UID/GID 1000. Ubuntu's base image ships a default `ubuntu` user at
 # 1000:1000 — i.e. exactly the typical host UID. The entrypoint creates a
-# fresh `claude` user mapped to HOST_UID; without this step its `useradd`
-# is skipped on collision and `runuser -u claude` then fails. Reusing the
+# fresh `opencode` user mapped to HOST_UID; without this step its `useradd`
+# is skipped on collision and `runuser -u opencode` then fails. Reusing the
 # baked-in `ubuntu` account would also silently inherit its supplementary
 # groups (sudo, adm, plugdev, …). Guarded so a future base image without
 # the default user doesn't break the build.
 RUN if getent passwd ubuntu >/dev/null; then userdel -r ubuntu; fi \
- && if getent group  ubuntu >/dev/null; then groupdel  ubuntu; fi
+    && if getent group ubuntu >/dev/null; then groupdel ubuntu; fi
 
 # NodeSource ships Node 24 LTS pinned to upstream releases — Ubuntu's archive
 # `nodejs` tracks an older minor and isn't LTS-pinned. `nodistro` is
@@ -141,35 +141,37 @@ RUN . /tmp/uv.env; set -e; ARCH=$(uname -m); \
 
 # npm-backed CLIs — pinned versions. Trust = npm's signed dist.integrity;
 # run `npm audit signatures <pkg>@<ver>` when bumping.
-# --ignore-scripts blocks lifecycle hooks for every package + transitive dep
-# (hard security boundary, kept on). claude-code 2.1.x ships its real binary
-# in a per-arch optional-dep package; the launcher's postinstall (install.cjs)
-# copies it over bin/claude.exe. Without it `claude` is a stub that errors at
-# exec. We invoke that one script ourselves — platform-detect + file copy,
-# no network/exec, audit-verified for 2.1.131; re-read on each bump.
+# opencode-ai ships its real binary in a per-arch optional-dep package; the
+# launcher's postinstall copies it over. Without it `opencode` is a stub that
+# errors at exec. We install with --ignore-scripts (blocks lifecycle hooks for
+# every package + transitive dep, hard security boundary) then explicitly invoke
+# the postinstall for opencode-ai only. It selects and copies the installed
+# platform binary, verifies it with `--version`, and only falls back to a
+# separate `npm install --ignore-scripts` when npm omitted the optional binary.
+# Re-review that script whenever the OpenCode pin changes.
 # `npm root -g` over a hardcoded path so we don't break on a different prefix.
 # npm tools carry version-only pins (no sha256): npm install verifies the
 # registry-advertised dist.integrity (registry-integrity, not provenance; CI
 # runs `npm audit signatures`). All three share this layer, so they share a COPY.
-COPY pins/claude-code.env pins/openspec.env pins/pnpm.env /tmp/
-RUN . /tmp/claude-code.env && . /tmp/openspec.env && . /tmp/pnpm.env \
- && npm install -g --ignore-scripts \
-      "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
-      "@fission-ai/openspec@${OPENSPEC_VERSION}" \
-      "pnpm@${PNPM_VERSION}" \
- && node "$(npm root -g)/@anthropic-ai/claude-code/install.cjs" \
- && rm /tmp/claude-code.env /tmp/openspec.env /tmp/pnpm.env
+COPY pins/opencode.env pins/openspec.env pins/pnpm.env /tmp/
+RUN . /tmp/opencode.env && . /tmp/openspec.env && . /tmp/pnpm.env \
+  && npm install -g --ignore-scripts \
+        "opencode-ai@${OPENCODE_VERSION}" \
+        "@fission-ai/openspec@${OPENSPEC_VERSION}" \
+        "pnpm@${PNPM_VERSION}" \
+   && node "$(npm root -g)/opencode-ai/postinstall.mjs" \
+   && rm /tmp/opencode.env /tmp/openspec.env /tmp/pnpm.env
 
 # tfenv — pure-bash terraform version manager. Arch-independent (just
 # bash scripts), so a single sha256 covers amd64 and arm64. We deliberately
 # ship NO terraform binary; the project's `.terraform-version` (or an
 # interactive `tfenv install <v>`) fetches the right version from
 # releases.hashicorp.com at runtime, in the same runtime-fetch class as
 # `pnpm dlx`/`uvx`. Installed under /opt (not /root) so image-level
-# version bumps aren't shadowed by the claude-code-root named volume.
+# version bumps aren't shadowed by the opencode-root named volume.
 # Placed after the heavier npm install so a tfenv version bump doesn't
 # invalidate that layer's cache (tfenv pins move far less often than the
-# claude-code/openspec/pnpm pins above).
+# opencode-ai/openspec/pnpm pins above).
 COPY pins/tfenv.env /tmp/tfenv.env
 RUN . /tmp/tfenv.env \
  && curl -fsSL "$TFENV_URL" -o /tmp/tfenv.tar.gz \
@@ -180,11 +182,11 @@ RUN . /tmp/tfenv.env \
  && ln -s /opt/tfenv/bin/terraform /usr/local/bin/terraform \
  && rm /tmp/tfenv.tar.gz /tmp/tfenv.env
 
-# Plain `tmux` mode swallows Shift+Enter so Claude's prompt sees only Enter,
+# Plain `tmux` mode swallows Shift+Enter so OpenCode's prompt sees only Enter,
 # forcing users to type `\` for a literal newline. `always` is required
-# (not `on`) because Claude does not send the kitty activation request that
-# `on` waits for — see claude-code#26629. /etc/tmux.conf, not
-# /root/.tmux.conf, because /root is masked by the claude-code-root named
+# (not `on`) because OpenCode does not send the kitty activation request that
+# `on` waits for. /etc/tmux.conf, not
+# /root/.tmux.conf, because /root is masked by the opencode-root named
 # volume at runtime. Harmless under tmux -CC: iTerm2 control mode bypasses
 # tmux's input layer. Placed after npm install so edits don't invalidate
 # the heavy AWS CLI / uv / glab / npm download layers above.
@@ -193,17 +195,17 @@ set -s extended-keys always
 set -as terminal-features "*:extkeys"
 EOF
 
-# DISABLE_AUTOUPDATER=1 keeps the pinned CLAUDE_CODE_VERSION authoritative —
-# without it, claude auto-replaces itself at runtime, defeating the
+# OPENCODE_DISABLE_AUTOUPDATE=1 keeps the pinned OPENCODE_VERSION authoritative —
+# without it, opencode auto-replaces itself at runtime, defeating the
 # --ignore-scripts supply-chain pinning above. Bump the image to upgrade.
-ENV CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
-    DISABLE_AUTOUPDATER=1 \
+ENV OPENCODE_EXPERIMENTAL_AGENT_TEAMS=1 \
+    OPENCODE_DISABLE_AUTOUPDATE=1 \
     IS_SANDBOX=1 \
     LANG=C.UTF-8 \
     LC_ALL=C.UTF-8
 
 # Container starts as root so the entrypoint can chown /root to the host
-# UID, then drops privileges via runuser. Steady-state, claude runs as the
+# UID, then drops privileges via runuser. Steady-state, opencode runs as the
 # host user with no effective / permitted / ambient capabilities — the
 # kernel clears those on the UID→non-zero transition; the bounding set
 # retains the setup caps but is inert under `no-new-privileges`. Do not
@@ -216,4 +218,4 @@ WORKDIR /workspaces
 COPY --chmod=0755 entrypoint.sh /usr/local/bin/entrypoint.sh
 
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
-CMD ["claude"]
+CMD ["opencode"]