# Architecture: Remote OpenCode Coding Agent Container ## Fit - The repository currently contains only `.twig.toml`; there is no application, service, or existing container setup to extend. - `Dockerfile` extends the official multi-architecture OpenCode v2 image `ghcr.io/anomalyco/opencode:2.0.26`, installs Git, curl, and mise, and creates a non-root runtime user. OpenCode and mise versions are pinned. - `docker/entrypoint.sh` configures the OpenCode v2 service password and Git's credential helper from runtime environment, sets the disposable working directory, and starts the foreground OpenCode server in service mode. - `docker/git-credential-env` supplies HTTPS credentials only for the configured Git host, directly from environment variables; it does not write the password to Git config or a credential store. - `docker/mise-shell` runs OpenCode shell commands through `mise exec`, so a repository's declared tools are auto-installed when the agent runs commands in that repository. - `docker-compose.yml` supplies restart/log policies, read-only root filesystem, temporary workspaces and home, and loopback-only port publishing. - `.env.example` documents required runtime variables without secrets. `README.md` documents build, run, Tailscale access, and remote-branch persistence. ## Endpoints None added by this repository. The upstream OpenCode v2 browser/API server listens on container TCP port `49374`. ## Data No durable data stores. `/workspace` and the OpenCode user's home are tmpfs mounts and are erased when the container stops. Git clones, generated files, OpenCode sessions, and temporary mise downloads are therefore disposable. The writable image layer is not used for session data. The remote Git repository is the persistence layer: completed work is pushed to a branch and proposed through a PR. ## Flow 1. Docker Compose starts one disposable container run per coding task and injects `.env` values at runtime. Restarting between tasks clears the session's tmpfs state. 2. The non-root entrypoint checks required settings, applies `OPENCODE_SERVER_PASSWORD` to the ephemeral OpenCode service config, configures `git credential.helper` to invoke the environment-backed helper, and starts `opencode serve --service --hostname 0.0.0.0 --port 49374` in the foreground. 3. The browser loads the OpenCode UI from the server over the published host port. OpenCode server authentication is enabled with runtime credentials. 4. The user/agent clones a fresh repository into `/workspace`, works on a branch, and pushes over HTTPS using the helper. After the branch/PR is remote, the container is restarted before the next task; no workspace data is saved on shutdown/restart. 5. Docker's health check requests the server UI with authentication. On macOS, Tailscale Serve on the host proxies a tailnet-only HTTPS name to the Compose-published loopback port. ## External - Tailscale on the macOS host; recommended access is `tailscale serve` proxying `http://127.0.0.1:49374`, not a public listener or direct LAN bind. - OpenCode-supported model providers (for example `ANTHROPIC_API_KEY`), injected into the container as runtime environment variables. - Git HTTPS remote, configured with `GIT_HOST`, `GIT_USERNAME`, and `GIT_PASSWORD`; credentials are runtime-only. SSH credentials are outside this first version. - OpenCode v2 is pinned to `2.0.26` (official multi-arch image). mise is pinned to `v2026.10.7`. No language runtimes are installed in the image.