# 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](adr/0011-opencode-connection-boundary.md) first. ## Four components, not one | Component | What it is | Where it runs | |-----------|------------|---------------| | OpenCode client | `opencode` TUI/CLI, or `opencode attach ` | 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 ```toml [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 ```sh # 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 ```sh 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: ```sh # 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.