Skip to content

MARKDOWN SOURCE

Raw
# Remote OpenCode Agent

An ephemeral, browser-accessible OpenCode v2 container for a Mac mini (Apple silicon). The official OpenCode image and mise binary are version-pinned and ARM64-capable; the Dockerfile also supports AMD64. No language runtimes are baked into the image—repositories declare their own tools in `mise.toml` or `.mise.toml`.

## Build and run

1. Create a local environment file and protect it:

   ```sh
   cp .env.example .env
   chmod 600 .env
   ```

2. Edit `.env` and set:
   - `OPENCODE_SERVER_PASSWORD`: a long random browser/API password (the Basic Auth username is `opencode`).
   - `GIT_HOST`, `GIT_USERNAME`, `GIT_PASSWORD`: the exact HTTPS host and an account/token able to push branches. For GitHub, a fine-grained PAT with the repository's contents read/write permission is sufficient.
   - Provider API keys as needed, for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.

   The required secret values are blank in `.env.example`; Compose refuses to start until you set them. Secrets are injected at container start and are not copied into the image. The Git credential helper only returns the username/password for HTTPS requests to the exact `GIT_HOST`; it never persists the Git password. The OpenCode server password is applied to its service config in the container's temporary home.

3. Build and start:

   ```sh
   docker compose up --build -d
   docker compose ps
   docker compose logs -f agent
   ```

   The OpenCode v2 web/API server listens on **TCP 49374** inside the container. Compose publishes it only on host loopback at `127.0.0.1:49374` by default. Override the host-side port with `HOST_PORT` if needed.

## Access from Tailscale

Keep the Docker port bound to `127.0.0.1`; do not change it to `0.0.0.0` or publish it on a LAN/public interface. On the macOS host, enable Tailscale Serve for the tailnet and proxy its HTTPS endpoint to the local container port:

```sh
tailscale serve --bg http://127.0.0.1:49374
tailscale serve status
```

Open the HTTPS URL shown by `tailscale serve status` from a device on your tailnet. Authenticate with username `opencode` and the `OPENCODE_SERVER_PASSWORD` value. Restrict access further with your Tailscale ACLs/grants. Remove the proxy with `tailscale serve reset`.

If you set a non-default `HOST_PORT`, use that host port in the Serve command.

Tailscale Serve terminates HTTPS on the Mac and forwards to the loopback-only Docker publish. The server binds to `0.0.0.0` only inside its isolated container network; the host port is not publicly or LAN-published.

## Repository and persistence workflow

- Use one task per container run. Start with a fresh clone under `/workspace`, then use the browser UI's project picker to open it. For example:

  ```sh
  git clone https://github.com/OWNER/REPOSITORY.git /workspace/REPOSITORY
  cd /workspace/REPOSITORY
  git switch -c feature/your-task
  ```

- Create a feature branch, make changes, and push the branch to the configured remote. Open the PR on the Git hosting service.
- **The remote branch/PR is the persistence layer.** `/workspace`, the OpenCode home/session state, and mise's installed tool/cache data are tmpfs mounts. They are discarded when the container stops or restarts; there are no repository bind mounts or named data volumes.
- After pushing the branch and opening the PR, start the next task with `docker compose restart agent`. This clears the tmpfs workspace, tool installs, and OpenCode session state so no repository is carried into the next task.
- `restart: unless-stopped` brings the service back after a crash or host reboot, but does not preserve the previous session. Docker rotates the container logs (10 MB × 3 files).
- Keep your provider and Git credentials in the host `.env` file or another runtime env-injection mechanism; never commit them. The Docker daemon administrator can inspect container environment, so protect access to the Mac and Docker.

## Operational notes

- The container runs as the unprivileged `opencode` user, has a read-only root filesystem, drops Linux capabilities, and uses `no-new-privileges`.
- `mise` (`v2026.10.7`) runs OpenCode shell commands in the selected repository directory and installs that repository's declared tools on demand. The image includes Git, curl, and mise, but no Node, Python, or other language runtime.
- The `software-factory` skill is shipped in the image and available to the agent for substantial feature work; it guides product, architecture, program-design, and vertical-slice planning.
- OpenCode (`2.0.26`) and mise versions are pinned in `Dockerfile`; update them intentionally and rebuild to upgrade.
- The server health check uses the authenticated `/api/info` endpoint. Check status with `docker compose ps`.
- The agent can execute repository code and has outbound network access for model APIs, Git remotes, and mise downloads. Only use repositories you trust; tailnet-only access does not constrain container egress.

Remote OpenCode Agent

An ephemeral, browser-accessible OpenCode v2 container for a Mac mini (Apple silicon). The official OpenCode image and mise binary are version-pinned and ARM64-capable; the Dockerfile also supports AMD64. No language runtimes are baked into the image—repositories declare their own tools in mise.toml or .mise.toml.

Build and run

  1. Create a local environment file and protect it:

    cp .env.example .env
    chmod 600 .env
    
  2. Edit .env and set:

    • OPENCODE_SERVER_PASSWORD: a long random browser/API password (the Basic Auth username is opencode).
    • GIT_HOST, GIT_USERNAME, GIT_PASSWORD: the exact HTTPS host and an account/token able to push branches. For GitHub, a fine-grained PAT with the repository's contents read/write permission is sufficient.
    • Provider API keys as needed, for example ANTHROPIC_API_KEY or OPENAI_API_KEY.

    The required secret values are blank in .env.example; Compose refuses to start until you set them. Secrets are injected at container start and are not copied into the image. The Git credential helper only returns the username/password for HTTPS requests to the exact GIT_HOST; it never persists the Git password. The OpenCode server password is applied to its service config in the container's temporary home.

  3. Build and start:

    docker compose up --build -d
    docker compose ps
    docker compose logs -f agent
    

    The OpenCode v2 web/API server listens on TCP 49374 inside the container. Compose publishes it only on host loopback at 127.0.0.1:49374 by default. Override the host-side port with HOST_PORT if needed.

Access from Tailscale

Keep the Docker port bound to 127.0.0.1; do not change it to 0.0.0.0 or publish it on a LAN/public interface. On the macOS host, enable Tailscale Serve for the tailnet and proxy its HTTPS endpoint to the local container port:

tailscale serve --bg http://127.0.0.1:49374
tailscale serve status

Open the HTTPS URL shown by tailscale serve status from a device on your tailnet. Authenticate with username opencode and the OPENCODE_SERVER_PASSWORD value. Restrict access further with your Tailscale ACLs/grants. Remove the proxy with tailscale serve reset.

If you set a non-default HOST_PORT, use that host port in the Serve command.

Tailscale Serve terminates HTTPS on the Mac and forwards to the loopback-only Docker publish. The server binds to 0.0.0.0 only inside its isolated container network; the host port is not publicly or LAN-published.

Repository and persistence workflow

  • Use one task per container run. Start with a fresh clone under /workspace, then use the browser UI's project picker to open it. For example:

    git clone https://github.com/OWNER/REPOSITORY.git /workspace/REPOSITORY
    cd /workspace/REPOSITORY
    git switch -c feature/your-task
    
  • Create a feature branch, make changes, and push the branch to the configured remote. Open the PR on the Git hosting service.

  • The remote branch/PR is the persistence layer. /workspace, the OpenCode home/session state, and mise's installed tool/cache data are tmpfs mounts. They are discarded when the container stops or restarts; there are no repository bind mounts or named data volumes.

  • After pushing the branch and opening the PR, start the next task with docker compose restart agent. This clears the tmpfs workspace, tool installs, and OpenCode session state so no repository is carried into the next task.

  • restart: unless-stopped brings the service back after a crash or host reboot, but does not preserve the previous session. Docker rotates the container logs (10 MB × 3 files).

  • Keep your provider and Git credentials in the host .env file or another runtime env-injection mechanism; never commit them. The Docker daemon administrator can inspect container environment, so protect access to the Mac and Docker.

Operational notes

  • The container runs as the unprivileged opencode user, has a read-only root filesystem, drops Linux capabilities, and uses no-new-privileges.
  • mise (v2026.10.7) runs OpenCode shell commands in the selected repository directory and installs that repository's declared tools on demand. The image includes Git, curl, and mise, but no Node, Python, or other language runtime.
  • The software-factory skill is shipped in the image and available to the agent for substantial feature work; it guides product, architecture, program-design, and vertical-slice planning.
  • OpenCode (2.0.26) and mise versions are pinned in Dockerfile; update them intentionally and rebuild to upgrade.
  • The server health check uses the authenticated /api/info endpoint. Check status with docker compose ps.
  • The agent can execute repository code and has outbound network access for model APIs, Git remotes, and mise downloads. Only use repositories you trust; tailnet-only access does not constrain container egress.