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

5.8 KiB

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 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: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.