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).
136 lines
5.8 KiB
Markdown
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.
|