phoebus_os/docs/OPENCODE.md
Phoebus 3d43f8c6c8 feat(executor): add an OpenCode server capability probe
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).
2026-09-21 20:01:44 -07:00

136 lines
5.8 KiB
Markdown

# 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 <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)
```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.