​
One public API

Allternit exposes one public origin:
That origin is the Cloud API (cmd/allternit-cloud-api). Browsers, SDKs, and CI talk only to it. The Allternit API (cmd/allternit-api, port 8013) is the data-plane runtime. It holds per-instance SQLite state (sessions, office bindings, local workspaces). It is never a public hostname. The Cloud API authenticates the caller, picks a healthy node, and relays the request.
Do not point production clients at http://localhost:8013 or at any second public gateway. Local 8013 is for desktop and development only.

​
Which API do I call?

​
Topology

​
Authentication at a glance

See Authentication.

​
Data-plane relay

Namespaces that store state on the node (agent sessions, Office, beta research) are Cloud API handlers. They do not keep a second copy of that state in Postgres.
  1. Authenticate the Clerk session.
  2. Resolve the caller’s default healthy node (desktop, paired box, or provisioned instance). Online means a recent heartbeat.
  3. Forward the original request — including the caller’s Authorization header — over the node’s outbound relay WebSocket.
  4. Stream the node’s response back. Nothing is cached or rewritten.
If the account has no healthy node, the Cloud API returns HTTP 428 (pair a device). Pair a runtime or start a provisioned instance, then retry.

​
Three ways to run the data plane

Local desktop

Allternit Desktop runs Allternit API and Gizzi on the machine. Pair it to your account.

User-paired (BYOC)

Install the runtime on your VPS, approve the pairing code, keep the node private.

Allternit-provisioned

Paid path: Cloud API creates an isolated instance that auto-pairs and phones home.

​
Next

Cloud API

Pairing, relay, hosted and provisioned compute, Cowork, health.

Allternit API

Data-plane binary, local port 8013, SQLite, what is never public.

Authentication

Clerk JWTs, virtual keys, device tokens.