README
¶
relay-proxy
Standalone Go reverse proxy that forwards HTTP requests to an upstream LLM endpoint (default opencode.ai/zen/v1). Runs on each relay VM in the self-hosted multi-cloud fleet (Epic 42), reachable over HTTP with per-VM token auth — the X-Relay-Token header is the security boundary (WireGuard was removed in worklog 0447).
Workspace pods never reach relay-proxy directly; the in-cluster cmd/relay-router dials each VM's public IP and injects the token.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/healthz |
none | 200 OK (no body) — token-exempt, for router/controller health checks |
GET |
/metrics |
none | Prometheus-format metrics — token-exempt |
* |
/* |
X-Relay-Token |
Transparent proxy to UPSTREAM_URL; 401 on missing/mismatched token (crypto/subtle.ConstantTimeCompare) |
/healthz and /metrics are exempt so the router can probe liveness without knowing the per-VM token.
Metrics
| Metric | Type | Description |
|---|---|---|
relay_requests_total{status} |
counter | Proxied request count by HTTP status code |
relay_egress_bytes_total |
counter | Total response body bytes proxied |
relay_keepalive_total |
counter | Keepalive probes sent to upstream |
Configuration
Flags read with precedence: flag > env var > hardcoded default.
| Flag | Env var | Default | Description |
|---|---|---|---|
--upstream |
UPSTREAM_URL |
https://opencode.ai/zen/v1 |
Upstream LLM endpoint |
--listen |
LISTEN_ADDR |
0.0.0.0:8080 |
Listen address |
--token |
RELAY_TOKEN |
(empty) | Shared-secret token the relay-router must present in X-Relay-Token. Required when the VM is part of a token-gated fleet. |
--keepalive-interval |
KEEPALIVE_INTERVAL |
30s |
Upstream probe interval |
Build
# From project root — cross-compiles for both architectures
make relay-bin
# Manual
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o deploy/relay-proxy-arm64 ./cmd/relay-proxy/
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o deploy/relay-proxy-amd64 ./cmd/relay-proxy/
Run locally
UPSTREAM_URL=https://opencode.ai/zen/v1 \
RELAY_TOKEN=shared-secret \
LISTEN_ADDR=127.0.0.1:8080 \
go run ./cmd/relay-proxy/
Deployment
Distributed to relay VMs via cloud-init (SHA-256 verified) from controller.inferenceRelay.artifact.urls; the cloud-init writes the per-VM token so the VM boots already token-gated. The token is generated by the controller (controller/internal/relay/reconciler.go) and stored in the relay-vm-tokens Secret keyed by provider slot. Token rotation = destroy + reprovision the VM.
See design/stories/epic-42-multi-cloud-inference-relay/README.md Layer 7 for the cloud-init template and the WireGuard→HTTPS+token supersession banner.
Documentation
¶
There is no documentation for this package.
Source Files