Daemon Backend Opencode

OpenCode Daemon Backend — Flag Discovery Entrypoint

The installed CLI's own help is the authority for OpenCode flags; this page is only the entrypoint. Conversion rules, key safety, and persistence live in the parent reference/cli-backends/SKILL.md. This page also owns the OpenCode operational core (install, auth, run flags, warm server, custom agents) migrated from the retired shell-manual bash reference.

Install & verify

# Official install script
curl -fsSL https://opencode.ai/install | bash

# Or install with a Node.js package manager
npm install -g opencode-ai      # also works with bun/pnpm/yarn

# Confirm it is on PATH
opencode --version

Discover flags from the installed CLI

1. Run, in bash: opencode --version, opencode --help, and opencode run --help. The daemon backend wraps opencode run, so opencode run --help is the relevant flag surface. These are local read-only commands; no session is started.
2. Translate what you found into backend_options with the parent's generic conversion rules. Nothing OpenCode-specific is added to that contract here.

Example: model and reasoning variant

OpenCode selects models as provider/model via -m, --model, and exposes provider-specific reasoning effort as --variant (see opencode run --help for both). Through backend_options, plain scalars become --flag <value>:

{
  "backend": "opencode",
  "tasks": [{
    "task": "Implement and validate the change.",
    "tools": [],
    "backend_options": {
      "model": "anthropic/claude-sonnet-4-5",
      "variant": "high"
    }
  }]
}
// argv: --model anthropic/claude-sonnet-4-5 --variant high

The model and variant vocabularies belong to the installed CLI and the selected provider — LingTai does not validate, enumerate, or simulate them.

Condensed opencode run flag surface

Illustrative, not a catalog — verify every flag against opencode run --help on the installed CLI before relying on it in automation; OpenCode moves quickly. Through backend_options, plain scalars become --flag <value>.

Subscription & auth

Authenticate at least one provider before relying on OpenCode for work:

opencode auth login          # interactive provider selection
opencode auth login -p openai
opencode auth list           # or: opencode auth ls

OpenCode stores provider credentials in ~/.local/share/opencode/auth.json and also loads provider keys from the environment and from a project .env file. For the curated OpenCode Go subscription use the opencode-go preset with OPENCODE_GO_API_KEY and https://opencode.ai/zen/go/v1 (chat wire only).

Official docs: https://opencode.ai/docs/

Warm server for repeated calls

Starting a fresh OpenCode run can cold-boot MCP servers. For many short calls, keep a server warm:

# Session 1: save a generated password where another shell can read it
pwfile=/tmp/opencode-server-password
openssl rand -hex 16 > "$pwfile"
chmod 600 "$pwfile"
OPENCODE_SERVER_PASSWORD="$(cat "$pwfile")" opencode serve --port 4096

# Session 2: read the same password and attach
opencode run --attach http://localhost:4096 \
  --password "$(cat /tmp/opencode-server-password)" \
  --dir /path/to/repo \
  "Explain async/await in this codebase"

Custom agent with constrained permissions

Deny-by-default: opencode agent create denies any omitted permission in the generated agent frontmatter.

mkdir -p .opencode/agent
opencode agent create \
  --path .opencode/agent/reviewer.md \
  --description "Read-only reviewer for docs and code diffs" \
  --mode primary \
  --permissions read,grep,glob

opencode run --agent reviewer "Review this diff; do not edit files."

Available permissions include bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, and skill.

Harness boundary

OpenCode reserves --format at the validation layer: the daemon owns opencode run --format json so its per-line JSON event parsing keeps working, and passing --format in backend_options refuses the whole batch before spawn. Beyond that, do not re-set harness-owned surfaces: session flags (--session / --continue) belong to daemon(action="ask", input={"id": ..., "message": ...}) resume (opencode run --session <opencode_session_id> --format json ...), and the completion MCP is injected through the OPENCODE_CONFIG_CONTENT environment variable — not argv — so breaking either silently breaks progress/result extraction and completion enforcement.

In daemon.json, OpenCode's backend_harness_argv holds a sentinel token pair that the runner converts into the OPENCODE_CONFIG_CONTENT environment variable rather than real argv flags.

Key Commands

Best Practices

1. Use a clean worktree. OpenCode can edit files. Isolate risky runs in /tmp/... worktrees so you can inspect or discard changes safely.
2. Set --dir explicitly. Avoid running against the wrong repository when the bash working directory is ambiguous.

Troubleshooting