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).
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 selecteddeepseek:deepseek-v4-flashpresent.--opencode-test→validated model response: {"phoebus":"ok"}(real inference), exit 0.- The GUI bridge
ai_checkover OpenCode applied 8 reviewed changes from a realdeepseek-v4-flashproposal. sys askover OpenCode proposed a read-onlyhistoryaction and executed it deterministically.- Authentication: no credential →
authentication_required; wrong →authentication_rejected; correct →model_catalogand a successful real inference. - Transport policy: plain
httpto 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.