Remote OpenAI-compatible servers

What this is for

Two distinct concepts in Blueprint that look superficially similar:

• Hosts — Linux/macOS machines Blueprint OWNS via SSH. Push-install the svc, manage their lifecycle, drive llama-server from end to end. See Adding a host.
• Remote servers — OpenAI-compatible HTTP endpoints someone ELSE operates. You probe /v1/health, /v1/models, /metrics; you read their state. You don't restart them, don't push install, don't manage their lifecycle. THIS card.

Use Remote servers when your team has a shared vLLM box behind a load balancer that you don't want each developer SSHing into. Or when you're targeting a paid endpoint (OpenAI, Anthropic, Together, Anyscale) and want the same Dashboard view across local and managed sources.

How to add one

1. Dashboard → Remote servers → Add server.
2. Fill in:
   • Label — what the card shows ("team vllm", "openai-prod")
   • Base URL — e.g. http://gpu-1.internal:8080 (the OpenAI- compatible /v1/ prefix is appended automatically)
   • API key — bearer token (or sk-... for OpenAI). Stored in plaintext in ~/.blueprint/remotes.json; treat as you would ~/.aws/credentials.
3. Save. The probe runs immediately.

What the probe checks

For each registered remote, Blueprint hits:

• GET /v1/health (if it 404s, that's fine — OpenAI itself doesn't expose this, we fall back to /v1/models)
• GET /v1/models — used to confirm auth + extract the available model list
• GET /metrics — Prometheus scrape if available (vLLM and llama-server both expose this). Powers the latency + throughput tiles on the card.

The card shows green / yellow / red per probe and refreshes every few seconds. If a remote goes dark, the card surfaces the last error so you can debug.

What you can do with a registered remote

• Send chat requests from the Inference tab (pick the remote from the dropdown)
• See live throughput in the metrics tile
• Compare against your local serve side-by-side — useful for A/B testing model upgrades before pushing them to prod

You CAN'T from this surface:

• Restart the remote
• Pull models onto it
• Apply a new config

For that, register it as a Host (assumes you have SSH access).

Common pitfalls

• Mixed-up Hosts vs Remote servers: if it's a Linux box you have SSH access to and want to manage end-to-end, it's a Host. If it's an HTTP URL with an API key, it's a Remote server.
• Self-signed TLS: Blueprint uses the system trust store. A remote with a self-signed cert will fail the probe with a TLS error. Either install the cert system-wide or front it with a proper cert (Caddy, Let's Encrypt).
• Storing the API key in plaintext: a future iteration moves this to the OS keychain (same path as the SSH bearer-token caching already does for Hosts). Until then, treat remotes.json like any other credentials file — chmod 600, don't commit, etc.