Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt

Use this file to discover all available pages before exploring further.

Podflare has two auth surfaces. This page covers API auth — the bearer token SDKs send on every request. The control plane (humans logging into a dashboard to manage orgs, keys, and billing) will be built on Clerk once the web app ships.

​
API auth model

  • Every request to /v1/* except /v1/healthz requires Authorization: Bearer <key>.
  • Valid keys are configured server-side (env var in v0, DB later).
  • A dev-mode toggle disables enforcement entirely for local work.

​
Configuring hostd

​
PODFLARE_API_KEYS
string (comma-separated)
Comma-separated list of valid bearer tokens. Any of these authenticates a request. If unset and hostd is bound to a loopback address, auth is silently disabled (dev mode). Hostd refuses to start otherwise.
​
PODFLARE_AUTH_DISABLED
bool
default:"false"
Set to 1 to bypass auth entirely. Only useful for local dev / the SSH-tunnel loop. Logs a loud warning at startup.
​
PODFLARE_HOSTD_ADDR
string
default:"127.0.0.1:7070"
Where hostd binds. A non-loopback bind + no keys + no disable flag is refused at startup — we won’t accidentally expose an unauth’d API.

​
SDK usage

from podflare import Sandbox

# Explicit
sbx = Sandbox(api_key="pk_your_key_here")

# Or via env
# export PODFLARE_API_KEY=pk_...
sbx = Sandbox()

​
Headers

The SDK sets three headers, all pass-through to hostd:
HeaderPurpose
Authorization: Bearer <key>API auth (this page).
traceparent: 00-<trace>-<span>-<flags>W3C Trace Context for span nesting.
content-type: application/jsonRequest body shape.

​
MCP server

Pass the key in the MCP server’s env block so it forwards on every sandbox call: 
{
  "mcpServers": {
    "podflare": {
      "command": "node",
      "args": ["/absolute/path/to/podflare/mcp/dist/index.js"],
      "env": {
        "PODFLARE_HOSTD_URL": "https://api.podflare.ai",
        "PODFLARE_API_KEY": "pk_your_key_here"
      }
    }
  }
}

​
Errors

  • 401 Unauthorized — no key, or the key isn’t in hostd’s allowlist. Response body: {"error": "missing Authorization: Bearer <key>"} or {"error": "invalid api key"}.

​
What’s coming (Clerk control plane)

Next steps once we build the dashboard:
  1. User signs up via Clerk (email, Google, GitHub — social login + MFA).
  2. User lands in a Podflare workspace (Clerk org).
  3. Dashboard lets them CRUD API keys, see usage, view traces.
  4. Keys are stored in our database with scopes + rotation support, not the env var baseline v0 uses.
  5. The SDK flow above stays identical — only the key issuance surface changes.
Contributions welcome; the control-plane repo is planned separately.