Cloud API - Allternit Docs

Overview

The Allternit Cloud API is the only public API. It is the hosted control plane that binds user accounts to self-hosted and managed data-plane nodes. It provides the runtime pairing protocol, the browser-to-runtime relay, hosted runtime lifecycle, Allternit-provisioned instances, the BYO-VPS deploy wizard, the Cowork Runtime execution API, and the /v1 model gateway. The API is built from cmd/allternit-cloud-api and runs at https://api.allternit.com in production (Postgres). The Allternit API (:8013, SQLite) is the private data plane — never a public hostname. See API Overview. The /v1/chat/completions model gateway is on this origin.

Base URL

https://api.allternit.com

Public health endpoints require no authentication. Runtime pairing creation and exchange are public (like an OAuth device flow). All other endpoints require either a Clerk session JWT or a runtime device token in the Authorization: Bearer <token> header.

Runtime pairing

First-party device pairing binds a desktop or VPS runtime to a human account without giving the runtime the human’s Clerk session token. The runtime generates an Ed25519 keypair, polls for approval, and exchanges the pairing for a revocable device credential.

Pairing endpoints

Method	Path	Auth	Description
POST	`/api/v1/runtime-pairings`	Public	Create a pairing request.
POST	`/api/v1/runtime-pairings/exchange`	Public	Exchange an approved pairing for a device token.
GET	`/api/v1/runtime-pairings/code/:code`	Clerk / device	Inspect a pairing by user code.
POST	`/api/v1/runtime-pairings/code/:code/approve`	Clerk / device	Approve a pairing request.
POST	`/api/v1/runtime-pairings/code/:code/deny`	Clerk / device	Deny a pairing request.
GET	`/api/v1/runtime-devices`	Clerk / device	List paired runtimes.
POST	`/api/v1/runtime-devices/verify-token`	Device token	Introspect a device token.
DELETE	`/api/v1/runtime-devices/:id`	Clerk	Revoke a runtime.
POST	`/api/v1/runtime-devices/:id/heartbeat`	Device token	Runtime heartbeat.
POST	`/api/v1/runtime-devices/:id/rotate`	Device token	Rotate device credential.
POST	`/api/v1/runtime-devices/:id/revoke-self`	Device token	Self-revoke a runtime.

Create a pairing

curl -X POST https://api.allternit.com/api/v1/runtime-pairings \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production VPS",
    "runtimeType": "vps",
    "hostname": "prod-01",
    "platform": "linux-amd64",
    "version": "0.1.0",
    "publicKey": "base64url-encoded-32-byte-public-key",
    "capabilities": [
      "runtime:connect",
      "runtime:execute",
      "runtime:files",
      "runtime:terminal",
      "providers:connect",
      "providers:use"
    ]
  }'

Response

{
  "pairingId": "pair_abc123",
  "deviceCode": "secret",
  "userCode": "ABCD-2345",
  "challenge": "secret",
  "verificationUrl": "https://platform.allternit.com/pair?code=ABCD-2345",
  "expiresAt": "2026-08-13T20:00:00Z",
  "pollIntervalSeconds": 2
}

Exchange a pairing

The runtime signs the challenge with its Ed25519 private key and polls the exchange endpoint.

curl -X POST https://api.allternit.com/api/v1/runtime-pairings/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "pairingId": "pair_abc123",
    "deviceCode": "secret",
    "signature": "base64url-ed25519-signature-of-allternit-runtime-pairing:pairingId:challenge"
  }'

Response

{
  "runtimeId": "rt_xyz789",
  "userId": "user_123",
  "userEmail": "[email protected]",
  "organizationId": "org_456",
  "deviceToken": "allternit_runtime_...",
  "tokenType": "Bearer",
  "expiresAt": "2026-11-11T19:50:00Z",
  "capabilities": ["runtime:connect", "runtime:execute", "runtime:files", "runtime:terminal", "providers:connect", "providers:use"]
}

While approval is pending, the endpoint returns HTTP 428:

{
  "error": "authorization_pending",
  "status": "pending"
}

Capability scopes

Capability	Allows
`runtime:connect`	Heartbeat and accept relay connections.
`runtime:execute`	Generic API execution through the relay.
`runtime:files`	File and workspace endpoints.
`runtime:terminal`	Terminal and PTY endpoints.
`providers:connect`	Write provider credentials.
`providers:use`	Read and use provider connections.

Paired computers

A user can pair one of their own machines (a Mac, a Linux box, a VPS) as a remote computer. Their devices can then view it and take it over, and the Allternit Factory can run bots on it, all over the private Allternit mesh. Pairing records the organization that was active when the code was made. Members of that organization see the computer too and can use it, marked shared: true.

Method	Path	Auth	Description
POST	`/api/v1/computers/pairing-codes`	Clerk / device	A single-use code (`XXXX-XXXX`, 10 minutes) and the command to run on the machine: `allternit computer pair <code>`.
POST	`/api/v1/computers/pair`	the code	Redeems a code: `{ code, name, os? }` → `{ computerId, secret, controlUrl, authKey, authKeyExpiresAt }`. `authKey` joins the mesh, and `secret` signs the machine’s reports.
POST	`/api/v1/computers/paired/:id/report`	`x-allternit-computer-secret`	The machine reports `{ meshIp, vncReady, name? }`. `meshIp` must be in `100.64.0.0/10`. `allternit computers serve` does this every minute.
POST	`/api/v1/computers/paired/self`	device (a cloud computer’s)	A cloud computer pairs itself, so the Factory can run bots on it. Same answer as `/pair`, plus `{ name, cloudUrl }`. The computer is owned by the cloud computer’s owner and named `Cloud computer`. Calling again keeps the same `computerId`, and rotates the secret and mesh key. Any other device answers `403`, and so does a deleted cloud computer.
GET	`/api/v1/computers/paired`	Clerk / device	The caller’s computers plus their organization’s: `{ computers: [{ id, name, os, mesh_ip, vnc_ready, created_at, last_seen_at, shared, cloud_computer }] }`. `cloud_computer` is `true` for a cloud computer that paired itself.
DELETE	`/api/v1/computers/paired/:id`	Clerk / device	Unpairs one of the caller’s own computers.
POST	`/api/v1/computers/paired/:id/peer-ticket`	Clerk / device	A Factory peer ticket for the computer’s owner or an organization member: `{ ticket, computerId, meshIp, peerPort: 3019, expiresIn }`. A computer that isn’t the caller’s answers `404`. One that hasn’t joined the mesh yet answers `409`.

Cloud computers as paired computers

An Allternit cloud computer pairs itself the first time its allternit-api starts, using the runtime device token it was provisioned with (POST /api/v1/computers/paired/self). It saves the answer in ~/.allternit/computer/paired.json, the same file allternit computer pair writes. Then it joins the owner’s mesh with mesh-node, forwarding only the Factory engine’s peer port (3019), and reports its mesh address every minute. Its screen is never served over the mesh: you view a cloud computer through the app as before. The pairing is deleted when the cloud computer is deleted. The row links to the instance through paired_computers.provisioned_instance_id (migration 067). Each runtime mirrors a cloud computer’s pairing as a hidden computer (role factory_peer). That keeps it out of the Computers list, where the cloud computer already shows, while --on can still name it. Set ALLTERNIT_CLOUD_PEER=0 on a cloud computer to turn this off.

Peer tickets

A peer ticket is a data-plane JWT (EdDSA) with sub = the user, aud = the computer id and scope = factory:peer. It lives 5 to 15 minutes (ALLTERNIT_DP_JWT_TTL_SECS, default 600). The computer’s Factory engine checks it offline against GET /api/v1/auth/dp-jwks, and accepts only tickets addressed to itself. See Factory agents (--on <computer>).

Runtime relay

Once paired, a runtime opens an outbound WebSocket to the cloud API. A Clerk-authenticated browser can then proxy HTTP requests and WebSocket traffic to that runtime without exposing the runtime’s loopback API publicly.

Relay endpoints

Method	Path	Auth	Description
WS	`/api/v1/runtime-relay/connect/:id`	Device token	Runtime relay WebSocket.
POST	`/api/v1/runtime-devices/:id/proxy`	Clerk	Proxy an HTTP request to the runtime.
POST	`/api/v1/runtime-devices/:id/socket-ticket`	Clerk	Create a one-time WebSocket ticket.
WS	`/api/v1/runtime-devices/:id/socket?ticket=...`	Ticket	Browser WebSocket to the runtime.
POST	`/api/v1/runtime-devices/:id/viewer-token`	Clerk	Mint a live desktop (VNC) viewer token for a cloud computer.
GET	`/api/v1/runtime-devices/:id/viewer-check`	Clerk or `compute` token	Automated self-check of the live desktop path: is the cloud computer’s VNC socket reachable?

Proxy a request to a runtime

curl -X POST https://api.allternit.com/api/v1/runtime-devices/rt_xyz789/proxy \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/v1/health",
    "headers": {},
    "body": "",
    "bodyEncoding": "utf8"
  }'

The cloud API verifies ownership and capability, forwards the request over the runtime WebSocket, and streams the response back.

WebSocket ticket

For streaming endpoints, request a ticket first:

curl -X POST https://api.allternit.com/api/v1/runtime-devices/rt_xyz789/socket-ticket \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/api/v1/runs/run_123/events/stream"}'

Response

{
  "ticket": "ticket_uuid",
  "expiresInSeconds": 30
}

Connect to the ticketed WebSocket:

wscat -c "wss://api.allternit.com/api/v1/runtime-devices/rt_xyz789/socket?ticket=ticket_uuid"

Live desktop viewer token

“Sign in on the cloud computer” opens the computer’s desktop in the browser. The desktop is served by the cloud computer itself and tunnelled through its outbound relay connection, so no Sessions computer record and no shared secret are involved. The viewer token uses the same signed format as the Sessions computers ws-token (purpose vnc, computer_id set to the runtime id), is signed with that runtime’s own relay key (the digest cloud-api already stores for it, credential_hash), and lives 300 seconds. The runtime’s allternit-api checks it at GET /api/v1/runtime-viewer/vnc?token=… and proxies to its local VNC server (ALLTERNIT_RUNTIME_VNC_ADDR, default 127.0.0.1:5900). wsUrl carries a 30-second relay socket ticket: connect right away, and ask again to reconnect.

curl -X POST https://api.allternit.com/api/v1/runtime-devices/rt_xyz789/viewer-token \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "readOnly": false }'

{
  "token": "<signed token>",
  "expiresAt": "2026-10-03T12:05:00+00:00",
  "wsUrl": "wss://api.allternit.com/api/v1/runtime-devices/rt_xyz789/socket?ticket=<30 s ticket>",
  "runtimeId": "rt_xyz789"
}

readOnly is optional and defaults to false (signing in needs keyboard and mouse). Errors: 401 unauthenticated; 404 for an unknown, revoked, or someone else’s runtime (the same answer for all three); 409 not_a_cloud_computer for a Desktop or BYO runtime; 503 runtime_warming or runtime_offline when the computer is still waking or unreachable (a sleeping computer is woken the same way the relay proxy wakes it); 400 no_host when the request carries no host to build the public address from. No environment variable is required; ALLTERNIT_VIEWER_WS_BASE optionally overrides the public ws base (default: the request’s own host over wss://).

Checking the live desktop without a browser

GET /api/v1/runtime-devices/:id/viewer-check verifies the whole path a person would use, so it can be tested against any real cloud computer by a script or an orchestrator. It does the same ownership, cloud-computer and wake steps as viewer-token, then asks the runtime, over the relay with a 60-second view-only token, to connect to its VNC socket and read the RFB banner (GET /api/v1/runtime-viewer/vnc-check?token=… on the runtime, same token rules as the viewer). Nothing is opened or sent to the VNC server, and no session is created.

curl -s https://api.allternit.com/api/v1/runtime-devices/rt_xyz789/viewer-check \
  -H "Authorization: Bearer $ALLTERNIT_API_TOKEN"

{ "ok": true, "runtimeId": "rt_xyz789", "relay": "connected",
  "vnc": { "reachable": true, "rfb": "RFB 003.008", "latencyMs": 4 }, "checkedAt": "2026-10-04T12:00:00+00:00" }

On failure the body is { "ok": false, "runtimeId", "stage", "reason" } and the status says where it stopped:

Status	`stage` / `reason`	Meaning
401 / 404 / 409	none	Same as `viewer-token`: not signed in; unknown, revoked or someone else’s runtime; `not_a_cloud_computer`.
503	`wake` / `runtime_warming`, `runtime_offline`	The computer is still waking or can’t be reached. Retry in a minute.
504	`relay` / `runtime_timeout`	The runtime didn’t answer through the relay.
502	`relay` / `runtime_has_no_viewer`, `runtime_rejected_token`, `runtime_answered_<status>`	The runtime is too old to have the viewer route, or its relay key is out of date.
502	`vnc` / `vnc_unreachable`, `vnc_timeout`, `not_rfb`	The runtime is up but nothing (or something other than VNC) answers on `ALLTERNIT_RUNTIME_VNC_ADDR`.

A green check proves the relay, the token and the VNC server; it can’t prove a human can see pixels, so the first real “Sign in on the cloud computer” on a new image is still worth one look. Run it after provisioning a cloud computer and after changing the desktop image.

Allowed relay paths

The runtime proxy only accepts paths under the following prefixes:

/api, /viz, /sandbox, /vm-session, /rails, /stream, /terminal, /mcp,
/platform, /metrics, /alabs, /cowork, /webhooks, /ws, /panes, /status,
/health, /v1

Relayed data-plane namespaces

These Cloud API routes authenticate with a Clerk session, resolve the caller’s default healthy node, and relay the request to Allternit API on that node. They do not store a second copy of the resource in Cloud API Postgres.

Namespace	Paths	Docs
Agent sessions	`/api/v1/agent-sessions`	Agent Sessions
Office	`/api/v1/office/bindings`, `/bootstrap`, `/runtime/state`	Office
Beta research	`/api/v1/beta/research`, `/api/v1/beta/sessions`	Beta

HTTP 428 means the account has no healthy node (pair a desktop/VPS or start a provisioned instance). The original Authorization header is forwarded. SSE is not buffered.

Artifacts v2

Unlike the relayed namespaces above, artifacts are stored in Cloud API Postgres itself, so every surface sees the same records. That includes the ones made on a cloud computer or by gizzi. Routes are under /api/v2/artifacts, plus a no-auth public link route /api/v2/public/artifacts/{id} and /api/v2/org/artifact-settings. See Artifacts v2.

Provisioned instances

Paid subscriptions can get an Allternit-provisioned data-plane instance (isolated container, per-instance SQLite, auto-pair). These routes are control-plane only: they create/start/stop the instance. Traffic to Allternit API inside the instance still goes through the runtime relay.

Method	Path	Auth	Description
GET	`/api/v1/provisioned-instances`	Clerk	List your instances.
POST	`/api/v1/provisioned-instances`	Clerk + subscription	Create an instance.
GET	`/api/v1/provisioned-instances/:id`	Clerk	Instance status.
POST	`/api/v1/provisioned-instances/:id/start`	Clerk	Start a stopped instance.
POST	`/api/v1/provisioned-instances/:id/stop`	Clerk	Stop an instance.
GET	`/api/v1/provisioned-instances/:id/usage`	Clerk	Metering sessions.
DELETE	`/api/v1/provisioned-instances/:id`	Clerk	Destroy an instance.
GET	`/api/v1/provisioned-instances/:id/snapshots`	Clerk	Your restore points, oldest first, and the cap (`max`).
POST	`/api/v1/provisioned-instances/:id/snapshots`	Clerk	Take a restore point now (201). 409 at the cap.
POST	`/api/v1/provisioned-instances/:id/snapshots/:name/restore`	Clerk	Roll the computer back. A running computer is stopped, restored and started.
DELETE	`/api/v1/provisioned-instances/:id/snapshots/:name`	Clerk	Delete a restore point (204).
POST	`/api/v1/provisioned-instances/:id/exports`	Clerk	Start packing a downloadable copy (202), or return the one in progress.
GET	`/api/v1/provisioned-instances/:id/exports/:exportId`	Clerk	Copy status; `downloadPath` once `ready`.
GET	`/api/v1/computer-exports/:token`	Token in path	Stream the copy (`.tar.zst`).

Host registration (/api/v1/provisioned-hosts) is operator-only.

Restore points and downloadable copies

Restore points are disk-only Incus snapshots of the computer, named user-<UTC timestamp>. They are copy-on-write on the host’s btrfs pool, and an owner can keep 5 per computer. Internal snapshots (for example the cancel snapshot kept after a subscription ends) are never listed, restored or deleted through these routes. All of them need the computer to be running, stopped or sleeping (409 otherwise). A downloadable copy is an incus export of the whole computer (instance only, zstd) that the host prepares in the background and deletes 24 hours later. Poll the export until status is ready (or failed). The response then carries downloadPath, which works without a session header for one hour (downloadExpiresAt), so a plain link or <a download> streams it to disk:

curl -X POST https://api.allternit.com/api/v1/provisioned-instances/$ID/exports \
  -H "Authorization: Bearer <clerk-session-token>"
# → 202 {"export":{"id":"exp_…","status":"preparing",…}}
curl https://api.allternit.com/api/v1/provisioned-instances/$ID/exports/exp_… \
  -H "Authorization: Bearer <clerk-session-token>"
# → {"export":{"status":"ready","downloadPath":"/api/v1/computer-exports/<token>",…}}
curl -o computer.tar.zst https://api.allternit.com/api/v1/computer-exports/<token>

Restore a copy on any Incus host with incus import computer.tar.zst. Export jobs live in cloud-api’s memory: after a cloud-api restart, ask for a new copy. Separately from these owner controls, every customer computer is backed up off-site every night: encrypted incus export archives in R2, kept 8 days (plus Sunday copies for 35 days). Operator details and restore steps: infrastructure/computer-backup/README.md in the platform repo.

curl https://api.allternit.com/api/v1/provisioned-instances \
  -H "Authorization: Bearer <clerk-session-token>"

This is mode 3 in BYOC Overview. It is separate from Fly hosted runtimes.

Hosted runtimes

Paid users can provision managed runtimes as Fly Machines. The agent-daemon inside the machine auto-pairs using a one-time bootstrap token.

Hosted runtime endpoints

Method	Path	Auth	Description
GET	`/api/v1/hosted-runtimes`	Clerk	List hosted runtimes.
POST	`/api/v1/hosted-runtimes`	Clerk	Create a hosted runtime.
GET	`/api/v1/hosted-runtimes/entitlement`	Clerk	Get current plan entitlement.
POST	`/api/v1/hosted-runtimes/:id/start`	Clerk	Start a stopped runtime.
POST	`/api/v1/hosted-runtimes/:id/stop`	Clerk	Stop a runtime.
DELETE	`/api/v1/hosted-runtimes/:id`	Clerk	Destroy a runtime.

Create a hosted runtime

curl -X POST https://api.allternit.com/api/v1/hosted-runtimes \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "lax",
    "memoryMb": 1024,
    "name": "Allternit Hosted (lax)"
  }'

Response

{
  "id": "hr_abc123",
  "name": "Allternit Hosted (lax)",
  "region": "lax",
  "status": "starting",
  "runtimeDeviceId": null,
  "cpus": 1,
  "memoryMb": 1024,
  "idleTimeoutMinutes": 15,
  "lastActivityAt": "2026-08-13T19:50:00Z",
  "stopReason": null,
  "monthlyUsageSeconds": 0,
  "monthlyEstimatedCostUsd": 0.0,
  "createdAt": "2026-08-13T19:50:00Z",
  "startedAt": "2026-08-13T19:50:00Z",
  "stoppedAt": null
}

BYO-VPS deploy wizard

The wizard provisions a self-hosted runtime on Hetzner, DigitalOcean, AWS, or a manual SSH target. It runs idempotent bootstrap over SSH, joins the box to the mesh, registers it as a gizzi instance, and mints a one-time pairing token.

Wizard endpoints

Method	Path	Auth	Description
POST	`/api/v1/cloud/wizard/deployments`	Clerk	Start a wizard deployment.
GET	`/api/v1/cloud/wizard/deployments`	Clerk	List wizard sessions.
GET	`/api/v1/cloud/wizard/deployments/:id`	Clerk	Get wizard state.
POST	`/api/v1/cloud/wizard/deployments/:id/advance`	Clerk	Advance to the next step.
POST	`/api/v1/cloud/wizard/deployments/:id/resume`	Clerk	Resume after a human checkpoint.
POST	`/api/v1/cloud/wizard/deployments/:id/cancel`	Clerk	Cancel the wizard.
DELETE	`/api/v1/cloud/wizard/deployments/:id`	Clerk	Delete a terminal wizard session.
POST	`/api/v1/cloud/wizard/deployments/:id/bootstrap`	Clerk	Run or retry the bootstrap step.

Start a wizard

curl -X POST https://api.allternit.com/api/v1/cloud/wizard/deployments \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hetzner",
    "apiToken": "hetzner-api-token",
    "instanceName": "allternit-prod-01",
    "region": "fsn1",
    "instanceType": "cx21",
    "storageGb": 50
  }'

Response

{
  "deploymentId": "dep_abc123",
  "currentStep": "SelectProvider",
  "context": {
    "provider": "hetzner",
    "instanceName": "allternit-prod-01",
    "region": "fsn1",
    "instanceType": "cx21",
    "storageGb": 50
  }
}

The response is redacted: apiToken, sshPrivateKey, and sshPassword are never echoed.

Bootstrap the box

curl -X POST https://api.allternit.com/api/v1/cloud/wizard/deployments/dep_abc123/bootstrap \
  -H "Authorization: Bearer <clerk-session-token>"

Response

{
  "deploymentId": "dep_abc123",
  "status": "complete",
  "meshIp": "100.64.0.5",
  "instanceName": "allternit-prod-01",
  "url": "http://100.64.0.5:8013",
  "paired": true,
  "runtimeId": "rt_xyz789",
  "wizard": { ... }
}

If the bootstrap fails for a recoverable reason, retry the same request. Non-recoverable failures or exhausted attempt caps return HTTP 409:

{
  "error": "bootstrap_not_retryable",
  "recoverable": false,
  "bootstrapAttempts": 3,
  "maxBootstrapAttempts": 3
}

Cowork Runtime

Runs are the core execution unit in the Cowork Runtime. The cloud API exposes run lifecycle, event streaming, schedules, approvals, jobs, and checkpoints.

Run endpoints

Method	Path	Description
POST	`/api/v1/runs`	Create a run.
GET	`/api/v1/runs`	List runs.
GET	`/api/v1/runs/:id`	Get a run.
PUT	`/api/v1/runs/:id`	Update run metadata.
DELETE	`/api/v1/runs/:id`	Delete a run.
POST	`/api/v1/runs/:id/start`	Start a run.
POST	`/api/v1/runs/:id/pause`	Pause a run.
POST	`/api/v1/runs/:id/resume`	Resume a run.
POST	`/api/v1/runs/:id/cancel`	Cancel a run.
POST	`/api/v1/runs/:id/attach`	Attach a client.
POST	`/api/v1/runs/:id/detach`	Detach a client.
GET	`/api/v1/runs/:id/attachments`	List attachments.
GET	`/api/v1/runs/:id/events`	List events.
GET	`/api/v1/runs/:id/events/stream`	Stream events (SSE).
WS	`/ws/runs/:id`	Stream events (WebSocket).
POST	`/api/v1/runs/:id/checkpoints`	Create a checkpoint.
GET	`/api/v1/runs/:id/checkpoints`	List checkpoints.
GET	`/api/v1/checkpoints/:id`	Get a checkpoint.
DELETE	`/api/v1/checkpoints/:id`	Delete a checkpoint.
POST	`/api/v1/runs/:id/restore`	Restore a checkpoint.

Create a run

curl -X POST https://api.allternit.com/api/v1/runs \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly sync",
    "description": "Sync production database",
    "mode": "local",
    "config": {
      "command": "./scripts/sync.sh",
      "args": ["--verbose"],
      "workingDir": "/workspace",
      "env": { "API_KEY": "secret123" },
      "resourceLimits": {
        "memoryMb": 2048,
        "cpuCores": 2.0,
        "diskGb": 10,
        "timeoutSeconds": 3600
      }
    },
    "autoStart": true
  }'

Response

{
  "id": "run_abc123",
  "name": "Nightly sync",
  "description": "Sync production database",
  "mode": "local",
  "status": "pending",
  "stepCursor": null,
  "totalSteps": null,
  "completedSteps": 0,
  "config": { ... },
  "ownerId": null,
  "tenantId": "user_123",
  "runtimeId": null,
  "runtimeType": null,
  "scheduleId": null,
  "createdAt": "2026-08-13T19:50:00Z",
  "updatedAt": "2026-08-13T19:50:00Z",
  "startedAt": null,
  "completedAt": null,
  "errorMessage": null,
  "errorDetails": null
}

Stream events

curl -N https://api.allternit.com/api/v1/runs/run_abc123/events/stream \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

Each SSE line is a JSON event:

{
  "id": "evt_001",
  "runId": "run_abc123",
  "sequence": 1,
  "eventType": "run_created",
  "payload": { "runName": "Nightly sync", "mode": "local" },
  "sourceClientId": null,
  "sourceClientType": null,
  "createdAt": "2026-08-13T19:50:00Z"
}

Schedule endpoints

Method	Path	Description
GET	`/api/v1/schedules`	List schedules.
POST	`/api/v1/schedules`	Create a schedule.
GET	`/api/v1/schedules/:id`	Get a schedule.
PUT	`/api/v1/schedules/:id`	Update a schedule.
DELETE	`/api/v1/schedules/:id`	Delete a schedule.
POST	`/api/v1/schedules/:id/enable`	Enable a schedule.
POST	`/api/v1/schedules/:id/disable`	Disable a schedule.
POST	`/api/v1/schedules/:id/trigger`	Trigger a schedule manually.

Approval endpoints

Method	Path	Description
GET	`/api/v1/approvals`	List approvals.
POST	`/api/v1/approvals`	Create an approval.
GET	`/api/v1/approvals/:id`	Get an approval.
POST	`/api/v1/approvals/:id/approve`	Approve a request.
POST	`/api/v1/approvals/:id/deny`	Deny a request.
POST	`/api/v1/approvals/:id/cancel`	Cancel an approval.

Health and metrics

Method	Path	Auth	Description
GET	`/api/v1/health`	Public	Database health.
GET	`/api/v1/health/ready`	Public	Readiness probe.
GET	`/api/v1/health/live`	Public	Liveness probe.
GET	`/api/v1/metrics`	Public	Prometheus metrics.

curl https://api.allternit.com/api/v1/health/live

{ "alive": true }

Error codes

Status	Code	Meaning
200	`ok`	Success.
201	`created`	Resource created.
204	`no_content`	Resource deleted.
400	`bad_request`	Invalid request parameters.
401	`unauthorized`	Missing or invalid authentication.
403	`forbidden`	Permission denied or plan limit reached.
404	`not_found`	Resource not found.
409	`conflict`	Resource conflict, non-retryable bootstrap, or terminal state mismatch.
410	`expired_token`	Pairing or credential expired.
428	`authorization_pending`	Pairing waiting for approval.
429	`rate_limited`	Too many requests.
502	`bad_gateway`	Upstream runtime or mesh error.
503	`service_unavailable`	Service not configured or runtime warming/offline.
504	`gateway_timeout`	Runtime did not respond in time.

Rate limits

Authenticated API routes: 60 requests per minute by default (RATE_LIMIT_RPM).
Public pairing and relay routes: 30 requests per minute by default (PUBLIC_RATE_LIMIT_RPM).

Rate limit headers are included on responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1723575600

Environment variables

Variable	Purpose
`PORT` / `BIND_ADDR`	HTTP server bind address.
`DATABASE_URL`	Postgres URL in production. SQLite is local/dev only.
`CLERK_ISSUER` / `CLERK_JWKS_URL`	Clerk JWT verification.
`ALLTERNIT_PLATFORM_URL`	Browser pairing origin.
`CORS_ALLOWED_ORIGINS`	Allowed browser origins.
`ALLTERNIT_CREDENTIALS_KEY`	AES-256-GCM key for provider tokens and wizard checkpoints.
`FLY_API_TOKEN` / `FLY_ORG_SLUG`	Hosted runtime provisioning.
`HEADSCALE_API_KEY`	Mesh enrollment service.
`STRIPE_WEBHOOK_SECRET`	Billing webhook verification.
`ALLTERNIT_VIEWER_WS_BASE`	Optional. Public ws base for the cloud computer viewer, e.g. `wss://api.allternit.com`. Default: the request’s host.

​Overview

​Base URL

​Runtime pairing

​Pairing endpoints

​Create a pairing

​Response

​Exchange a pairing

​Response

​Capability scopes

​Paired computers

​Cloud computers as paired computers

​Peer tickets

​Runtime relay

​Relay endpoints

​Proxy a request to a runtime

​WebSocket ticket

​Response

​Live desktop viewer token

​Checking the live desktop without a browser

​Allowed relay paths

​Relayed data-plane namespaces

​Artifacts v2

​Provisioned instances

​Restore points and downloadable copies

​Hosted runtimes

​Hosted runtime endpoints

​Create a hosted runtime

​Response

​BYO-VPS deploy wizard

​Wizard endpoints

​Start a wizard

​Response

​Bootstrap the box

​Response

​Cowork Runtime

​Run endpoints

​Create a run

​Response

​Stream events

​Schedule endpoints

​Approval endpoints

​Health and metrics

​Error codes

​Rate limits

​Environment variables

​Related pages

Overview

Base URL

Runtime pairing

Pairing endpoints

Create a pairing

Response

Exchange a pairing

Response

Capability scopes

Paired computers

Cloud computers as paired computers

Peer tickets

Runtime relay

Relay endpoints

Proxy a request to a runtime

WebSocket ticket

Response

Live desktop viewer token

Checking the live desktop without a browser

Allowed relay paths

Relayed data-plane namespaces

Artifacts v2

Provisioned instances

Restore points and downloadable copies

Hosted runtimes

Hosted runtime endpoints

Create a hosted runtime

Response

BYO-VPS deploy wizard

Wizard endpoints

Start a wizard

Response

Bootstrap the box

Response

Cowork Runtime

Run endpoints

Create a run

Response

Stream events

Schedule endpoints

Approval endpoints

Health and metrics

Error codes

Rate limits

Environment variables

Related pages