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).
3.4 KiB
3.4 KiB
ADR 0011: OpenCode connection boundary
- Status: Accepted
- Date: 2026-09-22
Context
The assignment requires a working OpenCode connection on the development/VM host
and from a separate user-controlled computer, while keeping the model untrusted
and the destructive broker local. OpenCode is an agent application, not an
OpenAI-compatible inference endpoint. Upstream's opencode serve exposes an
HTTP/JSON API (/global/health, /session, /config/providers, ...) with
optional basic authentication; opencode attach and opencode run --attach
connect a client to it.
Two facts shape the decision:
- A successful TCP connect, a health check or an HTTP 200 does not prove that a usable model is configured, nor that the model can emit a valid Phoebus proposal. The skill set must distinguish those states explicitly.
- The installed server, with no
OPENCODE_SERVER_PASSWORD, binds loopback and warns that it is unsecured. Its/config/providersresponse includes the provider credentials in cleartext. Exposing that service to a LAN would leak those credentials and hand an agent's tool surface to the network.
Decision
- Four components are named separately and may live on different machines: the OpenCode client, the OpenCode server, the model inference service, and the Phoebus installer/broker. An OpenCode server URL is never placed in Phoebus's local-model endpoint field.
- Connection states are typed and honest.
phoebus-executor::opencode_serverprobes/global/healthand/config/providersand reports one ofDisconnected,AuthenticationRequired,ReachableNoModel,Incompatible, orReady.Readymeans reachable, healthy, API-compatible and holding at least one model; it still does not prove a valid proposal round-trip. The probe keeps only counts from/config/providers, never the credentials it may contain. - Remote access is loopback plus an authenticated encrypted tunnel (SSH
port-forward, WireGuard, or equivalent). The probe accepts plain
http://only, because a direct TLS-less LAN bind is not an approved transport. - The OpenCode agent never inherits Phoebus privilege. Its tools, shell, file and plugin access are outside Phoebus's execution path. Destructive product actions still go through the local typed broker and local human approval. The OpenCode configuration is written mode 0600 and carries no credentials.
- The installer's AI step keeps using its own bounded transport. OpenCode is an optional operator workflow, not a replacement for the typed proposal transport; a future adapter must perform a real prompt round-trip and parse a versioned proposal before it may claim compatibility.
Consequences
- Remote OpenCode is not a one-click feature: the operator runs a tunnel. This is deliberate; the alternative is an unauthenticated credential-leaking agent endpoint on the LAN.
- The capability probe is testable against fake HTTP servers and against a real
opencode serve(env-gatedPHOEBUS_OPENCODE_PROBE), so compatibility is verified rather than assumed. - Developer use (this repository) and assistant use (approved bounded facts and typed proposals) remain clearly separated by tools and permissions.
Status
Accepted. The probe and its tests are implemented; end-to-end installation does not depend on OpenCode.