Docs

Quickstart

Three calls: get a computer, run something on it, move to another one of yours. The base URL is https://gateway.cerver.ai and every call carries your key.

1. Get a key

Any key works: a trial key from one call with no email, or one from the dashboard after you sign up. Sessions started with an account-wide key go to your default project. A project key keeps them in that project.

curl -X POST https://gateway.cerver.ai/v2/auth/temp-signup
export CERVER_API_KEY=ck_...

GET /v2/start says where you stand and gives the next call, ready to run. It works with or without a key.

curl https://gateway.cerver.ai/v2/start \
  -H "Authorization: Bearer $CERVER_API_KEY"

2. Get a computer and run on it

curl -X POST https://gateway.cerver.ai/v2/sessions \
  -H "Authorization: Bearer $CERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_name": "hello-cerver", "compute": { "provider": "e2b" } }'
# → { "session_id": "..." }

curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/run \
  -H "Authorization: Bearer $CERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "uname -a; nproc; free -h" }'

3. Move it to another computer

curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/change-compute \
  -H "Authorization: Bearer $CERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "compute": { "compute_id": "comp_..." } }'

A session can move to any computer that is already on your account: your own machines, and cloud computers that are running. List their ids with GET /v2/computes. Moving straight to a fresh cloud computer by provider name is not shipped yet. For that, start a new session on that provider.

The session keeps its transcript and history. Close it with DELETE /v2/sessions/SESSION_ID when you are done.

For agents

If you are an agent setting Cerver up for someone, read these two files first. They are written for you and kept current.

• cerver.ai/skill.md: when to use Cerver, the session model, every call with its body.
• cerver.ai/llms.txt: the short reference of every primitive.

If you are a person with an agent, paste this into it. It gets a key, lists your computers and runs a first task.

Keys

Send the key as a bearer token on every call. Keys start with ck_.

Authorization: Bearer $CERVER_API_KEY

• Project keys are tied to one project and are the keys that start sessions. Use one per product, or one per customer when you want hard separation.
• Account keys are for the dashboard and the CLI. They can read everything but cannot start a session.
• Publishable keys start with pk_, are spend-capped and are safe in a browser. The chat element uses one.

The CLI reads the key from CERVER_API_KEY. The MCP server reads CERVER_API_TOKEN. Set both to the same value if you use both.

Model and provider keys do not live in Cerver. They stay in your vault and are fetched when a run needs them.

Computers

A computer is anywhere work can run. Every one of them takes the same calls: run code, stream output, read and write files.

List what your account can use right now:

curl https://gateway.cerver.ai/v2/computes \
  -H "Authorization: Bearer $CERVER_API_KEY"

E2B and Vercel work out of the box. Cloudflare is not switched on yet. Cloud providers can also run on your own provider account when you add its key.

Choose a computer

Say where a session runs when you create it. There are three ways.

# a provider: Cerver starts a fresh computer there
{ "compute": { "provider": "e2b" } }

# one specific computer, such as your laptop
{ "compute": { "compute_id": "comp_..." } }

# no computer: a hosted model turn
{ "compute": { "provider": "online" } }

# what the work needs: Cerver picks the best computer that fits
{ "compute": { "needs": { "gpu": true, "tools": ["ffmpeg"] } } }

An agent can make this choice itself. Before it picks, it can ask which computers fit the job:

POST /v2/pool/find
{ "needs": { "os": "linux", "ram_gb": 4, "tools": ["ffmpeg"] } }

# or as a link
GET /v2/pool/find?gpu=A100&tools=ffmpeg,docker

The answer lists the computers that fit, best first: your own machines, then cloud computers that are already on, then new ones your providers would start. Each comes with why it fits and what to do after it starts, such as "install ffmpeg after it starts". The answer also lists the computers that do not fit and what each one lacks, for example "offline" or "no GPU". When nothing fits, it says what to add.

The needs you can ask for: gpu (true, or a name like A100), gpu_memory_gb, ram_gb, cpu_cores, disk_gb, os (macos or linux), arch, tools, desktop and online. Your machines report their hardware and installed tools every 30 seconds. A machine whose relay is older says "not reported" instead of being guessed at; reinstall to update it.

Send the same needs as compute to start a session on the best match. If nothing fits, the call fails with 409 no_matching_compute and the same explanation. A GPU need starts a fresh Modal or Daytona computer with that GPU.

Switch mid-task

Move a running session to a different computer. Cerver carries the transcript over and starts the agent on the new machine with the history as context.

POST /v2/sessions/:id/change-compute

{ "compute": { "compute_id": "comp_..." } }      # one of yours
{ "compute_priority": ["comp_a...", "comp_b..."] }   # first one that is up
{ "compute": { "needs": { "gpu": true } } }       # the best computer that fits

A session can move to any computer that is already on your account: your own machines, and cloud computers that are running. List their ids with GET /v2/computes. Moving straight to a fresh cloud computer by provider name is not shipped yet. For that, start a new session on that provider.

Files on the old computer do not move by themselves. Keep work in a repo or write results into the session if the next computer needs them.

Your own machine

One command turns a Mac, a Linux box or a server into a computer on your account. It opens an outbound connection only, so there is no port to expose.

curl -fsSL https://cerver.ai/install.sh | bash

The machine then shows up in GET /v2/computes. Send work to it by id, and it uses the agents and logins already on that machine.

Live screen

Show the screen of a session's computer in your own page, and let a person take over the mouse and keyboard.

First ask whether this session's computer can stream and take input:

GET /v2/sessions/:id/screen

Your server mints a viewer token. It is for one session, expires after 15 minutes by default and is view-only unless you ask for control.

POST /v2/sessions/:id/screen/token
{ "control": true, "ttl_seconds": 900 }
# → { "token": "cvs_..." }

Then drop the element in. Video flows from the machine to the browser directly.

<script src="https://cerver.ai/embed/cerver-screen.js"></script>
<cerver-screen session="SESSION_ID" token="cvs_..."></cerver-screen>

Your compute pool routing soon

Your compute pool is every computer your agents can use: the provider accounts you connected and your own machines. GET /v2/pool shows it: each provider with the kinds of computer it gives you (sandbox, desktop, GPU) and whose account pays, your machines and whether they are online, what is on now, and what you could add. GET /v2/start leads with the same line, for example "Your pool: E2B, Vercel and 1 machine."

Today the agent picks a computer for each session, by provider, by id or by what the work needs, or moves it mid-task, and a session with no computer named runs on your pool in order: your machines first, then your provider accounts. Keeping computers of each kind warm, limits per kind and automatic routing by task are not shipped yet. See the design.

Sessions

A session is one piece of work. It always has a transcript, and it records the computer, the agent, the steps and the cost.

POST   /v2/sessions                  create
GET    /v2/sessions                  list
GET    /v2/sessions/search?q=...     search
GET    /v2/sessions/:id              read, with transcript
GET    /v2/sessions/:id/metrics      latency and cost
POST   /v2/sessions/:id/run          run code      { "code": "..." }
POST   /v2/sessions/:id/run/stream   same, streamed as it runs
POST   /v2/sessions/:id/run-llm      a model turn  { "input": "...", "model": "..." }
POST   /v2/sessions/:id/pause        pause
POST   /v2/sessions/:id/resume       resume
DELETE /v2/sessions/:id              close

Tag a session with your own customer id and every cent it spends is attributed to that customer.

{ "compute": { "provider": "online" },
  "metadata": { "external_user_id": "9b2c6f1e-4a7d-4e2b-8c1a-3f5e7d9a0b12" } }

Agents and models

The agent driving a session is separate from the computer it runs on. Pick it at create time with harness, and change it later without losing the history.

# start with Claude Code on one of your machines
POST /v2/sessions
{ "harness": "claude",
  "compute": { "compute_id": "comp_..." },
  "metadata": { "cli_tool": "claude", "bootstrap_prompt": "Fix the failing test." } }

# hand the same session to Codex
POST /v2/sessions/:id/switch-tool
{ "cli_tool": "codex" }

# keep the agent, change the model
POST /v2/sessions/:id/switch-tool
{ "cli_model": "claude-haiku-4-5-20251001" }

CLI agents can run on a subscription you already pay for when they run on your machine. API models run on your provider key from your vault, or on Cerver credits.

Crons

Run an agent on a schedule. Schedules are five-field cron expressions in UTC. Each firing opens a session.

POST /v2/projects/:slug/crons
{ "name": "nightly-report",
  "schedule": "0 6 * * *",
  "prompt": "Summarise yesterday's signups and post them to the team.",
  "harness": "claude" }

GET    /v2/projects/:slug/crons            list
PATCH  /v2/projects/:slug/crons/:id        change or pause
POST   /v2/projects/:slug/crons/:id/run    fire now
DELETE /v2/projects/:slug/crons/:id        remove

A cron can run a prompt, a saved agent, a workflow, or call an HTTPS webhook.

Workflows

A workflow is a fixed list of steps you write. Cerver runs them top to bottom and passes each output to the next. Use one when the steps are known; use an agent when they are not.

POST /v2/projects/:slug/workflows            create
POST /v2/projects/:slug/workflows/:id/run    run
GET  /v2/runs/:runId                         steps, status, cost

Chat in your product

Two lines put a chat on your site. It opens a session per visitor, streams replies and stores the conversation.

<script src="https://cerver.ai/embed/cerver-chat.js"></script>
<cerver-chat pk="pk_live_..."
  system-prompt="You answer questions about our docs."></cerver-chat>

Building your own UI instead? Open a session with "provider": "online" and post each message to /run-llm. The reply streams back as text_delta events, followed by a usage event with the cost.

Cost and caps

Set a spending limit and runs stop when it is reached. You can also cap each agent type separately.

PUT /v2/account/spending-limit
{ "limit_usd": 20 }

# a limit per agent type
{ "harness_limits": { "claude": 10, "codex": 5 } }

GET /v2/account/usage-by-customer     spend per customer
GET /v2/sessions/:id/metrics          what one run cost

Endpoints

The calls most products need. The base URL is https://gateway.cerver.ai.

The full list, with every body, is in skill.md.

Pricing

Compute is a fixed monthly package from $20: you bring your own provider keys and the provider bills you directly. Agents plans start at $29 a month. See pricing.

Help

Stuck, or something here is wrong? Write to hello@cerver.ai.