OpenCode is an agent application, not an OpenAI-compatible endpoint. Add a typed probe over /global/health and /config/providers that distinguishes disconnected, authentication required, incompatible, reachable-no-model and ready, and never returns provider credentials. Expose it as phoebus-installer --opencode-probe. Document the four components, host and tunnelled remote workflows, and the Phoebus assistant boundary (ADR 0011).
5.8 KiB
OpenCode connection workflow
OpenCode is used in two clearly separated ways:
- Developer workflow — on this repository, inspecting sanitized evidence. Full tool access (shell, files, plugins) is fine because it runs as you, on your machine, against your checkout.
- Phoebus assistant connection — approved, bounded system facts and validated typed proposals. It must never inherit the developer tool permissions and never receives secrets.
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 |
usually the same machine as the client or the model |
| Model inference service | DeepSeek/OpenAI, or a local OpenAI-compatible server (Ollama, llama.cpp, ...) | 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 Phoebus's local-model endpoint field.
An OpenCode server is an agent application; it is not an OpenAI-compatible
/v1/chat/completions endpoint. Pointing Phoebus's local provider at it will
fail, and would be the wrong trust boundary even if it parsed.
Capability probe (never assume compatibility)
phoebus-installer --opencode-probe http://127.0.0.1:4096
It is read-only and prints a typed state, exiting nonzero unless a model is available:
| State | Meaning |
|---|---|
disconnected |
TCP connect failed; the service is down |
authentication_required |
the server answered 401/403; supply the password/tunnel |
incompatible |
a health response arrived but the API shape is not the expected one |
reachable_no_model |
healthy server, no model configured |
ready |
reachable, healthy, API-compatible, and ≥1 model configured |
ready still does not prove the model can emit a valid Phoebus proposal;
that requires a real prompt round-trip and proposal parse. A health check or an
HTTP 200 is not that proof.
The probe reads /global/health and /config/providers, keeps only counts from
the latter, and never returns the provider credentials that upstream includes in
that response.
A. OpenCode on the development/VM host
# 1. Set a provider credential through the environment (never a file in git).
export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)" # 0600 file
# 2. Start the server on loopback only. Upstream warns when it is unsecured.
opencode serve --hostname 127.0.0.1 --port 4096
# 3. In another terminal, attach a client to it.
opencode attach http://127.0.0.1:4096
Keep the server on 127.0.0.1. Do not pass --mdns and do not bind 0.0.0.0
without authentication: the server's configuration API can expose provider
credentials.
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. SSH port-forwarding is the simplest approved transport:
# On the remote computer:
opencode serve --hostname 127.0.0.1 --port 4096
# From your machine (tunnel local 127.0.0.1:4096 -> remote loopback:4096):
ssh -N -L 127.0.0.1:4096:127.0.0.1:4096 you@remote.example
# Then, locally:
opencode attach http://127.0.0.1:4096
phoebus-installer --opencode-probe http://127.0.0.1:4096
The probe now sees a loopback endpoint and the tunnel supplies transport
authentication and encryption. If you cannot use a tunnel, set
OPENCODE_SERVER_PASSWORD and terminate TLS in front of the server; never
expose an unauthenticated plaintext service.
VM networking is not one thing
Inside a VM these are different endpoints and must not be confused:
| 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 |
C. Phoebus assistant boundary
When a Phoebus assistant uses OpenCode:
- Run the service unprivileged, with restricted filesystem access.
- Disable tools you do not need. OpenCode permission settings are not an operating-system security boundary; enforce isolation outside the prompt.
- Keep the destructive execution path in Phoebus's local broker with local human approval. The agent is never given a shell, root, credentials or private-file access.
- Keep credentials in protected runtime storage (0600, outside model context). Never forward disk passphrases or account passwords to OpenCode.
- Changing the model or connection invalidates any approval whose meaning depends on it; a reconnect must never replay an installation command.
Developer workflow note
For work on this repository, the developer OpenCode session may use full tools,
but only against a checkout and against sanitized test evidence. Do not feed
it VM disks, serial transcripts with credentials, *.pw files, or the
PHOEBUS_OPENCODE_* runtime inputs.
Verified evidence
phoebus-installer --opencode-probe http://127.0.0.1:41999against the installedopencode 1.18.32returnedready(3 providers, 27 models).- The same probe through a forwarded second loopback endpoint returned
ready. - A server deliberately bound to a LAN address without authentication
returned
authentication_requiredand exit status 1: the probe refuses to treat an unauthenticated service as usable. - Physical second-computer verification is BLOCKED in this environment (no second machine / no passwordless SSH); the forwarded-hop test is labelled as a host-local transport test, not a second computer.