# OpenCode connection workflow OpenCode is used in two clearly separated ways: 1. **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. 2. **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](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 | 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) ```sh 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 ```sh # 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: ```sh # 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:41999` against the installed `opencode 1.18.32` returned `ready` (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_required` and 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.