Skip to content

MARKDOWN SOURCE

Raw
# Program Design: Remote OpenCode Coding Agent Container

## Files

- `Dockerfile` — pinned multi-arch OpenCode v2 base, pinned mise binary, Git/curl, non-root user, runtime env defaults, port, health check, and entrypoint.
- `docker/entrypoint.sh` — validate required runtime settings, set up global Git helper and ephemeral workspace, then exec OpenCode in the foreground.
- `docker/git-credential-env` — Git credential protocol helper that returns HTTPS credentials only for `GIT_HOST`.
- `docker/mise-shell` — run shell tool commands through mise in the active repository directory, triggering auto-install for declared tools.
- `docker-compose.yml` — loopback port publication, tmpfs mounts, environment file, restart policy, and bounded local logs.
- `.dockerignore` — exclude secrets and non-build files from the build context.
- `.gitignore` — prevent a developer's real `.env` file from being committed.
- `.env.example` — variable names and safe placeholders; no credentials.
- `README.md` — build/run, architecture, Tailscale Serve setup, security notes, and branch/PR workflow.
- `tests/git-credential-env.sh` — focused checks for host/protocol scoping and Git helper operations.
- `docs/plans/remote-opencode-container/00-status.md` — approvals and slice progress.
- `docs/plans/remote-opencode-container/01-product.md` — approved product statement.
- `docs/plans/remote-opencode-container/02-architecture.md` — approved system boundaries and data flow.
- `docs/plans/remote-opencode-container/03-program-design.md` — implementation contract.
- `docs/plans/remote-opencode-container/04-slices.md` — approved implementation sequence.

## Types & signatures

```sh
# docker/entrypoint.sh
require_env() { name: string; }
main() { env: process environment; execs: opencode serve; }

# docker/git-credential-env (Git credential-helper protocol)
credential_helper(operation: "get" | "store" | "erase", stdin: Git credential fields)
  -> stdout: username/password fields only for protocol=https and host=GIT_HOST;

# docker/mise-shell
mise_shell(args: shell flags and command, cwd: active repository)
  -> execs: mise exec -- /bin/sh <flags> <command>;
```

```yaml
# Compose contract (values supplied from .env at runtime)
services.agent.environment:
  OPENCODE_SERVER_PASSWORD: required secret
  GIT_HOST: required hostname
  GIT_USERNAME: required secret/account name
  GIT_PASSWORD: required secret/token
  <provider API keys>: optional runtime secrets
services.agent.ports: ["127.0.0.1:${HOST_PORT}:49374"]
services.agent.tmpfs: [/workspace, /home/opencode, /tmp]
```

```dockerfile
# Runtime contract
USER opencode
EXPOSE 49374/tcp
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["serve", "--service", "--hostname", "0.0.0.0", "--port", "49374"]
```

## Call stack

- Startup: Compose env and tmpfs mounts → entrypoint validation, OpenCode password setup, and Git config → `exec opencode serve --service` → authenticated server/UI on `0.0.0.0:49374`.
- Git push: OpenCode tool invokes Git → Git invokes `git-credential-env get` → helper verifies HTTPS + exact `GIT_HOST` → Git authenticates using runtime username/password → branch is pushed to the remote.
- Health: Docker health check → authenticated HTTP request to the local OpenCode UI endpoint → healthy/unhealthy container status.
- Remote access: browser on tailnet → host Tailscale Serve HTTPS endpoint → host loopback port → Compose-published container port.

## Test plan

- `git credential helper returns credentials for configured HTTPS host` — helper returns exactly the configured username and password.
- `git credential helper does not send credentials to a different host` — helper returns no credential fields for any nonmatching host.
- `git credential helper ignores non-HTTPS remotes` — SSH and other protocols receive no HTTPS secret.
- `git credential helper ignores store and erase operations` — secrets are never written by the helper.
- `mise shell auto-installs declared tools` — an undeclared-at-image-build tool in `.mise.toml` is installed and available inside a repository shell.
- `docker compose config` — Compose interpolation is valid with a local `.env` and loopback-only port binding is retained.
- `docker buildx build --platform linux/arm64` — ARM64 image builds, reports the pinned OpenCode and mise versions, and runs as non-root.
- `container smoke test` — server responds on port 49374 with HTTP auth, health becomes healthy, and `/workspace` is writable/ephemeral.
- `Tailscale access check` — on the target Mac, host's Tailscale Serve URL loads the same UI while the Docker port remains loopback-only; requires the host's tailnet and ACL configuration.

## Least confident decisions

1. The official `2.0.26` image supports ARM64 and is the latest v2 release observed at planning time; keep this exact version pin until intentionally upgraded.
2. OpenCode v2 applies the injected password through its `service set password` setting before `serve --service`; verified against v2.0.26 (`/api/info` returns 200 with Basic Auth and 401 without it). The default username is `opencode`.
3. Docker Desktop for macOS supports the chosen Compose tmpfs options and `read_only` setup. Linux Compose tmpfs was verified; confirm final hardened config with Docker Desktop before using on the Mac mini.
4. `GIT_HOST` exact host matching is the right safe default for a single remote provider; supporting multiple hosts would require an explicit future interface.

Program Design: Remote OpenCode Coding Agent Container

Files

  • Dockerfile — pinned multi-arch OpenCode v2 base, pinned mise binary, Git/curl, non-root user, runtime env defaults, port, health check, and entrypoint.
  • docker/entrypoint.sh — validate required runtime settings, set up global Git helper and ephemeral workspace, then exec OpenCode in the foreground.
  • docker/git-credential-env — Git credential protocol helper that returns HTTPS credentials only for GIT_HOST.
  • docker/mise-shell — run shell tool commands through mise in the active repository directory, triggering auto-install for declared tools.
  • docker-compose.yml — loopback port publication, tmpfs mounts, environment file, restart policy, and bounded local logs.
  • .dockerignore — exclude secrets and non-build files from the build context.
  • .gitignore — prevent a developer's real .env file from being committed.
  • .env.example — variable names and safe placeholders; no credentials.
  • README.md — build/run, architecture, Tailscale Serve setup, security notes, and branch/PR workflow.
  • tests/git-credential-env.sh — focused checks for host/protocol scoping and Git helper operations.
  • docs/plans/remote-opencode-container/00-status.md — approvals and slice progress.
  • docs/plans/remote-opencode-container/01-product.md — approved product statement.
  • docs/plans/remote-opencode-container/02-architecture.md — approved system boundaries and data flow.
  • docs/plans/remote-opencode-container/03-program-design.md — implementation contract.
  • docs/plans/remote-opencode-container/04-slices.md — approved implementation sequence.

Types & signatures

# docker/entrypoint.sh
require_env() { name: string; }
main() { env: process environment; execs: opencode serve; }

# docker/git-credential-env (Git credential-helper protocol)
credential_helper(operation: "get" | "store" | "erase", stdin: Git credential fields)
  -> stdout: username/password fields only for protocol=https and host=GIT_HOST;

# docker/mise-shell
mise_shell(args: shell flags and command, cwd: active repository)
  -> execs: mise exec -- /bin/sh <flags> <command>;
# Compose contract (values supplied from .env at runtime)
services.agent.environment:
  OPENCODE_SERVER_PASSWORD: required secret
  GIT_HOST: required hostname
  GIT_USERNAME: required secret/account name
  GIT_PASSWORD: required secret/token
  <provider API keys>: optional runtime secrets
services.agent.ports: ["127.0.0.1:${HOST_PORT}:49374"]
services.agent.tmpfs: [/workspace, /home/opencode, /tmp]
# Runtime contract
USER opencode
EXPOSE 49374/tcp
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["serve", "--service", "--hostname", "0.0.0.0", "--port", "49374"]

Call stack

  • Startup: Compose env and tmpfs mounts → entrypoint validation, OpenCode password setup, and Git config → exec opencode serve --service → authenticated server/UI on 0.0.0.0:49374.
  • Git push: OpenCode tool invokes Git → Git invokes git-credential-env get → helper verifies HTTPS + exact GIT_HOST → Git authenticates using runtime username/password → branch is pushed to the remote.
  • Health: Docker health check → authenticated HTTP request to the local OpenCode UI endpoint → healthy/unhealthy container status.
  • Remote access: browser on tailnet → host Tailscale Serve HTTPS endpoint → host loopback port → Compose-published container port.

Test plan

  • git credential helper returns credentials for configured HTTPS host — helper returns exactly the configured username and password.
  • git credential helper does not send credentials to a different host — helper returns no credential fields for any nonmatching host.
  • git credential helper ignores non-HTTPS remotes — SSH and other protocols receive no HTTPS secret.
  • git credential helper ignores store and erase operations — secrets are never written by the helper.
  • mise shell auto-installs declared tools — an undeclared-at-image-build tool in .mise.toml is installed and available inside a repository shell.
  • docker compose config — Compose interpolation is valid with a local .env and loopback-only port binding is retained.
  • docker buildx build --platform linux/arm64 — ARM64 image builds, reports the pinned OpenCode and mise versions, and runs as non-root.
  • container smoke test — server responds on port 49374 with HTTP auth, health becomes healthy, and /workspace is writable/ephemeral.
  • Tailscale access check — on the target Mac, host's Tailscale Serve URL loads the same UI while the Docker port remains loopback-only; requires the host's tailnet and ACL configuration.

Least confident decisions

  1. The official 2.0.26 image supports ARM64 and is the latest v2 release observed at planning time; keep this exact version pin until intentionally upgraded.
  2. OpenCode v2 applies the injected password through its service set password setting before serve --service; verified against v2.0.26 (/api/info returns 200 with Basic Auth and 401 without it). The default username is opencode.
  3. Docker Desktop for macOS supports the chosen Compose tmpfs options and read_only setup. Linux Compose tmpfs was verified; confirm final hardened config with Docker Desktop before using on the Mac mini.
  4. GIT_HOST exact host matching is the right safe default for a single remote provider; supporting multiple hosts would require an explicit future interface.