MARKDOWN SOURCE
# 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 forGIT_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.envfile 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 on0.0.0.0:49374. - Git push: OpenCode tool invokes Git → Git invokes
git-credential-env get→ helper verifies HTTPS + exactGIT_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.tomlis installed and available inside a repository shell.docker compose config— Compose interpolation is valid with a local.envand 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/workspaceis 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
- The official
2.0.26image supports ARM64 and is the latest v2 release observed at planning time; keep this exact version pin until intentionally upgraded. - OpenCode v2 applies the injected password through its
service set passwordsetting beforeserve --service; verified against v2.0.26 (/api/inforeturns 200 with Basic Auth and 401 without it). The default username isopencode. - Docker Desktop for macOS supports the chosen Compose tmpfs options and
read_onlysetup. Linux Compose tmpfs was verified; confirm final hardened config with Docker Desktop before using on the Mac mini. GIT_HOSTexact host matching is the right safe default for a single remote provider; supporting multiple hosts would require an explicit future interface.