Skip to content

opencode-docker.md

Latest commit

 

History

History
139 lines (94 loc) · 5.63 KB

opencode-docker.md

File metadata and controls

139 lines (94 loc) · 5.63 KB

OpenCode Docker Runtime

The runner starts OpenCode inside Docker for solver and judge model calls. This page describes how credentials and config reach the container, and how to turn on extra logging.

What gets mounted

Each worker session bind-mounts three things into the container:

Host source Container path Mode Purpose
Eval workspace directory /workspace read-write Files the agent reads and edits
Isolated temp dir with copied ~/.local/share/opencode/auth.json /root/.local/share/opencode (auth.json inside) read-write OpenCode provider credentials
Repo opencode.json or opencode.jsonc (if present) /root/.config/opencode/<filename> read-only Provider/model config (no secrets)

The host auth.json is copied into a per-container temp directory, and that directory is bind-mounted to /root/.local/share/opencode so concurrent workers do not share or overwrite the same host file.

Provider access depends on 3 optional sources:

  1. ~/.local/share/opencode/auth.json
  2. passthrough env vars
  3. config referenced from opencode.json/opencode.jsonc placed in this repo root

Running the runner inside Docker

When the runner itself runs in a container with access to the host Docker socket, solver/judge workspaces and auth isolation dirs must live on a host-visible path. The Docker daemon resolves bind-mount sources on the host, not inside the runner container.

Pass --host-tmpdir to a directory that exists on the host and is bind-mounted into the runner container at the same path:

# on the host
mkdir -p /var/tmp/evals-runner

docker run \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/tmp/evals-runner:/var/tmp/evals-runner \
  ... \
  bun runner/run.ts \
    --model openai/gpt-4.1-mini \
    --host-tmpdir /var/tmp/evals-runner \
    --output generated/my-generated

When omitted, the runner uses the process temp directory (os.tmpdir(), typically /tmp). That works for local runs where the runner process and Docker daemon share the same filesystem namespace.

The runner creates per-session subdirectories under this root with prefixes evals-opencode- (workspaces) and evals-opencode-home- (isolated auth copies). They are removed when each session finishes.

Environment variable passthrough

The runner forwards matching host environment variables into the container with docker run -e.

A variable is passed when:

  1. It is set and non-empty in the host process environment, and
  2. Its name matches one of the default prefixes:
  • OPENCODE_
  • OPENAI_
  • ANTHROPIC_
  • GOOGLE_
  • GEMINI_
  • AZURE_
  • PARASAIL_
  • CLOUDFLARE_

Examples that are forwarded: OPENAI_API_KEY, CLOUDFLARE_API_TOKEN, OPENCODE_SERVER_LOG_LEVEL.

Unrelated variables (for example PATH, HOME, GITHUB_TOKEN) are not forwarded.

Extra prefixes

To forward additional prefixes, set a comma-separated list before running:

export OPENCODE_DOCKER_EXTRA_ENV_PREFIXES='MY_PROVIDER_,CUSTOM_GATEWAY_'
bun runner/run.ts --model openai/gpt-4.1-mini --output generated/my-generated

Extra prefixes are merged with the defaults above.

Debugging flags

Both bun runner/run.ts and bun runner/judge.ts accept:

--host-tmpdir

Optional host-visible temp root for solver/judge workspaces and isolated auth copies. Use when the runner runs inside a container with access to the host Docker socket. See Running the runner inside Docker.

--agent-logs

Streams OpenCode agent activity from the server SSE feed. Log lines are prefixed with [opencode-docker][...][agent] and include session lifecycle events, tool calls, and session errors.

This flag also:

  • Sets the in-container server log level to DEBUG
  • Enables --print-logs on the OpenCode server process

Use this when you need provider or session error details that do not appear in default output.

--verbose

Enables [opencode-trace] diagnostics for each OpenCode model call:

  • Call start/stop with model, port, timeout, and workspace directory
  • Phase transitions (structured-output, json-fallback, and so on)
  • Session ID when available
  • Heartbeats every 3 seconds with session status, message count, and latest assistant activity (tool runs, text, errors)

--verbose also turns on agent logging (equivalent to passing --agent-logs).

Example:

bun runner/run.ts \
  --model openai/gpt-4.1-mini \
  --output generated/my-generated \
  --agent-logs \
  --verbose

For judge runs:

bun runner/judge.ts \
  --model openai/gpt-5.3-codex \
  --input generated/my-generated \
  --agent-logs \
  --verbose

Related environment variables

Variable Default Effect
OPENCODE_STREAM_CONTAINER_LOGS enabled Set to 0 to stop streaming [container] docker logs
OPENCODE_SERVER_LOG_LEVEL INFO Server log level when --agent-logs is off
OPENCODE_SERVER_PRINT_LOGS off Set to 1 to enable --print-logs without --agent-logs
OPENCODE_DOCKER_EXTRA_ENV_PREFIXES unset Comma-separated extra env key prefixes to forward

When a run starts, the runner prints a single line summarizing the effective logging settings (serve log level, agent logs, verbose).