phoebus_os/docs/OPENCODE.md
Phoebus c16014ade8 feat(gui): select and validate OpenCode from the installer
Add an 'OpenCode agent' choice with server/password/provider/model fields,
a Test connection action, and a secret-free frontend state line the
harness asserts. Require exactly one installer session and assert the
current step and AI state instead of inferring from a screenshot. Add a
live-OpenCode acceptance make target and document the adapter, transport
policy, states and workflows (ADR 0011 updated).
2026-09-22 02:36:36 -07:00

8.2 KiB

OpenCode connection workflow

OpenCode is integrated as a real agent-server connection, not a renamed OpenAI-compatible endpoint. The adapter speaks OpenCode's session/message API and feeds the same strict proposal parser, evidence review and executor as the direct providers.

Read ADR 0011 first.

Four components, not one

Component What it is Where it runs
OpenCode client opencode TUI/CLI, or opencode attach <url> your machine
OpenCode server opencode serve — an HTTP/JSON agent API, not a model API same machine as the client or the model
Model inference service DeepSeek/OpenAI, or a local OpenAI-compatible server provider cloud or your LAN
Phoebus installer/broker the typed, privileged, local executor the target machine only

An OpenCode server URL does not go in the direct-provider endpoint field. Select the OpenCode backend instead; Phoebus speaks the agent protocol.

Configuration

[ai]
enabled = true
backend = "opencode"          # "direct" (default) or "opencode"
opencode_server = "http://127.0.0.1:4096"
opencode_provider = "deepseek"
opencode_model = "deepseek-chat"
# The server password is a secret: supply it at runtime, never here.

The server password is stored in protected runtime input (a 0600 file or the GUI secret pipe) and is separate from a direct provider API key.

Command line

# Read-only: classify the server. Exits nonzero unless a model catalog exists.
phoebus-installer --opencode-probe http://127.0.0.1:4096 \
  --opencode-provider deepseek --opencode-model deepseek-chat

# Acceptance: obtain and validate a real model response. Exits nonzero on any
# failure. This is the inference check, not a reachability check.
phoebus-installer --opencode-test http://127.0.0.1:4096 \
  --opencode-provider deepseek --opencode-model deepseek-chat \
  --opencode-password-file /path/to/server.pw

# Installer guidance through OpenCode (a real proposal is reviewed and applied).
phoebus-installer --ai-backend opencode \
  --opencode-server http://127.0.0.1:4096 \
  --opencode-provider deepseek --opencode-model deepseek-chat \
  --install --ai

# The installed assistant uses the same adapter.
sys ask --ai-backend opencode --opencode-server http://127.0.0.1:4096 \
  --opencode-provider deepseek --opencode-model deepseek-chat \
  "show the transaction history"

--opencode-password-file must be mode 0600, like the direct provider key file.

Graphical installer

On the AI model step choose OpenCode agent, then fill in the server URL, the server password (if the server has one), the provider and the model. Two actions are available:

  • Test connection obtains and validates a real model response (ai_test); it does not change the installation plan.
  • Connect and validate obtains a real proposal through OpenCode and runs the strict review (ai_check). Only then does the wizard allow continuing, and only then does the backend accept the AI prerequisite for installation.

Changing the server, provider, model or password — or editing the configuration — invalidates the validated state.

Connection states

phoebus-installer --opencode-probe prints one of:

State Meaning
insecure_transport the destination failed the transport policy
unreachable the server could not be reached
authentication_required the server returned 401 and no credential was supplied
authentication_rejected a credential was supplied and rejected
incompatible a response arrived but was not the expected API/JSON
reachable healthy server with no model catalog
model_catalog healthy server with a model catalog
selected_model_unavailable the chosen provider/model is not in the catalog
ready reserved for a real, validated model response (not the probe)

A model catalog is not readiness. The probe never returns ready; only a real inference that validates the response does.

Transport policy

  • Plain http:// is accepted only when the resolved destination is loopback. The host is resolved and the connection is pinned to the checked address, so a DNS answer that changes after the check cannot move the target.
  • Remote access is https:// (curl verifies the certificate; verification is never disabled) or an authenticated encrypted tunnel terminating on loopback (SSH -L, WireGuard, ...).
  • Redirects are disabled, the protocol is restricted to http,https, and connect time, total time, header/body sizes and response size are bounded.
  • A URL with userinfo, a path or a control character is rejected.

Security

  • The server the assistant talks to should run unprivileged with a restricted configuration. OpenCode permission settings are not an OS sandbox: run the Phoebus-facing server with a dedicated directory, no plugins, and no developer sessions, and keep the model credentials out of its reach where the deployment allows.
  • The adapter requests no tools per message ("tools": {...false}) as defence in depth, but that is not a substitute for process isolation.
  • Destructive product actions remain in the local typed broker with local human approval. The agent never receives a shell, root, credentials or private-file access, and disk/account passphrases are never sent to it.
  • The adapter creates a transient session per request, accepts only the completed assistant text parts (never user, tool or reasoning parts) and deletes the session afterwards, so installation facts are not retained.

A. OpenCode on the development/VM host

export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)"   # 0600 file
opencode serve --hostname 127.0.0.1 --port 4096
opencode attach http://127.0.0.1:4096        # interactive client
phoebus-installer --opencode-probe http://127.0.0.1:4096

Keep the server on 127.0.0.1; do not enable --mdns or bind 0.0.0.0 without authentication.

B. OpenCode on a separate user-controlled computer

Run the server on that computer bound to loopback and reach it through an authenticated encrypted tunnel:

# remote:
opencode serve --hostname 127.0.0.1 --port 4096
# local:
ssh -N -L 127.0.0.1:4096:127.0.0.1:4096 you@remote.example
phoebus-installer --opencode-probe http://127.0.0.1:4096

If a tunnel is impossible, set OPENCODE_SERVER_PASSWORD and terminate TLS in front of the server; never expose an unauthenticated plaintext service.

VM networking is not one thing

Endpoint Meaning
guest 127.0.0.1 the guest's own loopback
host 127.0.0.1 the host's loopback (invisible to the guest)
10.0.2.2 the QEMU user-net gateway to the host
192.168.x.y a real LAN address, reachable by other machines

A VM guest cannot name the host's loopback directly, and plain http to the gateway is refused by policy. The supported pattern is a host-local relay bound to the guest's loopback (the same shape as an SSH tunnel); the VM harness uses a tiny TCP forwarder for exactly this.

Verified evidence (2026-09-22)

  • opencode 1.18.32 (pinned manifest: v1.18.31; version mismatch noted).
  • --opencode-probe → model_catalog, 223 providers / 7915 models, 26 connected; the selected deepseek:deepseek-v4-flash present.
  • --opencode-test → validated model response: {"phoebus":"ok"} (real inference), exit 0.
  • The GUI bridge ai_check over OpenCode applied 8 reviewed changes from a real deepseek-v4-flash proposal.
  • sys ask over OpenCode proposed a read-only history action and executed it deterministically.
  • Authentication: no credential → authentication_required; wrong → authentication_rejected; correct → model_catalog and a successful real inference.
  • Transport policy: plain http to a LAN/global address → insecure_transport, exit 1, no request sent.
  • Real-HTTP integration tests cover status preservation, chunked multibyte bodies, oversized bodies, redirects, abrupt disconnects and authentication.
  • A separate physical computer remains unverified; a second server bound to the LAN address reached through a loopback tunnel is the remote-topology test.