Encrypted Local Proxy
Stock OpenAI clients cannot speak Spore’s end-to-end protocol. The encrypted
local proxy inside spore-node fixes that: your editor or SDK talks to
127.0.0.1, and the node encrypts before anything leaves your machine.
Plaintext never goes to api.sporeintel.com. The public
API stays available for tools that only need TLS; use this proxy when
you want the same E2E path as the web app.
The proxy is off by default. It binds loopback only — not your LAN.
Prerequisites
Section titled “Prerequisites”- Install and link a node.
- Create a user API key (
sk_spore_…) from Profile → API Keys. - Have at least one model serving in personal mode on a linked node for the default path (unqualified model ids). For community encrypted requests, community capacity must exist for that model and tier.
Start the proxy
Section titled “Start the proxy”spore proxy startOn first start it prompts for your sk_spore_ key (or pass
--api-key sk_spore_…, or set SPORE_USER_API_KEY). It also mints a local
sk_local_… key and prints it. Keys are stored in proxy_keys.json under
your Spore data dir (~/.config/spore/ by default).
Run the proxy together with the node:
spore start --proxyCheck whether it is up:
spore proxy statusDefault listen address:
http://127.0.0.1:18790/v1/api/v1 is served on the same port for clients that expect that path prefix.
Authentication
Section titled “Authentication”Every request needs a Bearer token — even on loopback:
| Key | Role |
|---|---|
sk_local_… | Issued by the proxy on first start. Prefer this in Cursor / OpenCode. |
sk_spore_… | Your Spore user API key. Also accepted by the proxy. |
Node-link keys (spore_…) are not valid on the proxy. Missing or wrong
Authorization returns 401.
curl http://127.0.0.1:18790/v1/models \ -H "Authorization: Bearer sk_local_YOUR_LOCAL_KEY"Point a client at it
Section titled “Point a client at it”curl http://127.0.0.1:18790/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk_local_YOUR_LOCAL_KEY" \ -d '{ "model": "qwen3.5-4b:8k", "messages": [{"role": "user", "content": "Hello!"}] }'Cursor
Section titled “Cursor”-
Open Settings → Models.
-
Enable OpenAI API Key and paste your
sk_local_…key (orsk_spore_…). -
Enable Override OpenAI Base URL and set:
http://127.0.0.1:18790/v1 -
+ Add Model with a Spore model id (
name:tier, see below). -
Verify — Cursor calls
/v1/modelson the proxy.
Keep the override off when you want Cursor’s own models; it is global.
OpenCode (spore launch)
Section titled “OpenCode (spore launch)”spore launch opencodeIf the proxy is healthy, launch points OpenCode at loopback. If not, it falls back to the public API and prints a warning that traffic will be plaintext — start the proxy first when you want encryption.
Model naming
Section titled “Model naming”Proxy model strings are rewritten before the encrypted upstream call:
| You send | Upstream routing |
|---|---|
name:tier (e.g. qwen3.5-4b:8k) | Personal + encrypted (default) |
name:tier:personal | Personal + encrypted |
name:tier:community | Community + encrypted |
Personal requests are free and only hit your own nodes. Community encrypted requests use the network and spend credits; they still never leave your machine in the clear.
:community exists only on the proxy. The public API does not accept that
suffix. Always include a context tier (8k, 32k, 64k, 128k, …).
GET /v1/models lists catalog ids; unqualified names are rewritten to personal
when you chat — the listing does not mint a separate :personal catalog.
What stays encrypted
Section titled “What stays encrypted”On the proxy path:
- Messages and tools are encrypted on your machine (AES-256-GCM).
- The session key is wrapped with X25519 for you and for the assigned node.
- The server only routes ciphertext and metadata (model, sizes, timing, reported token counts).
See End-to-End Encryption for the protocol. Hitting
https://api.sporeintel.com/api/v1 directly with a stock client remains the
plaintext OpenAI-compatible path described in the API docs.
Limitations
Section titled “Limitations”- Off by default — start it explicitly (
spore proxy startorspore start --proxy). - Loopback only — no LAN bind in this release.
- No menu-bar / UniFFI controls yet — CLI only for now.
- GitHub automations (Pi agent loop) use this proxy on the runner for
model turns (
127.0.0.1:18790). The runner starts it for the job. If the proxy cannot run, the job fails. There is no public-API fallback. See Automations. - Streaming to the client is reconstructed after decrypt; you get OpenAI-shaped chunks, not raw upstream ciphertext deltas.
- If the proxy is down,
spore launch opencodecan still use the public API with a warning. Prefer keeping the proxy up for E2E.
Related
Section titled “Related”- Running a Node
- Automations (Pi model turns use this proxy on the runner)
- End-to-End Encryption
- API (public plaintext OpenAI surface)