# 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 ; ``` ```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 : 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.