Skip to content

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.

  1. Install and link a node.
  2. Create a user API key (sk_spore_…) from Profile → API Keys.
  3. 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.
Terminal window
spore proxy start

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

Terminal window
spore start --proxy

Check whether it is up:

Terminal window
spore proxy status

Default listen address:

http://127.0.0.1:18790/v1

/api/v1 is served on the same port for clients that expect that path prefix.

Every request needs a Bearer token — even on loopback:

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

Terminal window
curl http://127.0.0.1:18790/v1/models \
-H "Authorization: Bearer sk_local_YOUR_LOCAL_KEY"
Terminal window
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!"}]
}'
  1. Open Settings → Models.

  2. Enable OpenAI API Key and paste your sk_local_… key (or sk_spore_…).

  3. Enable Override OpenAI Base URL and set:

    http://127.0.0.1:18790/v1
  4. + Add Model with a Spore model id (name:tier, see below).

  5. Verify — Cursor calls /v1/models on the proxy.

Keep the override off when you want Cursor’s own models; it is global.

Terminal window
spore launch opencode

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

Proxy model strings are rewritten before the encrypted upstream call:

You sendUpstream routing
name:tier (e.g. qwen3.5-4b:8k)Personal + encrypted (default)
name:tier:personalPersonal + encrypted
name:tier:communityCommunity + 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.

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.

  • Off by default — start it explicitly (spore proxy start or spore 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 opencode can still use the public API with a warning. Prefer keeping the proxy up for E2E.