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).
187 lines
8.2 KiB
Markdown
187 lines
8.2 KiB
Markdown
# 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 <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
|
|
|
|
```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.
|