API Reference
Everything an AI agent needs to use Cerver.
Base URL
https://gateway.cerver.ai
Authentication
Pass your API key in the Authorization header:
Authorization: Bearer ck_your_key
Use Cerver in this order
1. Create a session
Choose the tool and where it runs. The transcript starts here.
curl -X POST https://gateway.cerver.ai/v2/sessions \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_name": "compare-claude",
    "task": "Explain this PR",
    "harness": "claude",
    "compute": { "compute_id": "comp_..." },
    "metadata": {
      "cli_tool": "claude",
      "bootstrap_prompt": "Explain this PR"
    }
  }'
2. Continue the conversation
Append a user turn. If an agent is attached, Cerver forwards it.
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/input \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Now make it safer."
  }'
3. Switch the tool
Keep the same session, but continue with Codex instead of Claude.
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/switch-tool \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cli_tool": "codex",
    "harness": "codex",
    "compute": { "compute_id": "comp_..." },
    "content": "Continue from the transcript."
  }'
4. Switch compute
Move the session to another registered machine without losing context.
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/compute \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "compute": { "compute_id": "comp_other..." }
  }'
5. Read the transcript
Fetch exactly what happened: user turns, assistant turns, tools, and switch events.
curl "https://gateway.cerver.ai/v2/sessions/SESSION_ID?tail=50" \
  -H "Authorization: Bearer ck_YOUR_KEY"
6. Compare results
Create sibling sessions with the same prompt and different tools, then compare transcripts and metrics.
# Same task, different harness:
# claude session + codex session
GET /v2/sessions/:id?tail=50
GET /v2/sessions/:id/metrics
Core Session Shape
Pick the intelligence/tool layer with harness. Pick where it runs with compute. The transcript stays with the session.
{
  "session_name": "same-intent-claude-cli",
  "task": "Explain the tradeoff in 5 bullets",
  "harness": "claude",
  "compute": { "compute_id": "comp_..." },
  "metadata": {
    "cli_tool": "claude",
    "bootstrap_prompt": "Explain the tradeoff in 5 bullets",
    "working_dir": "/path/to/repo"
  }
}
compute can be {"provider":"vercel"}, {"provider":"e2b"}, {"compute_id":"comp_..."}, or null for transcript-only sessions.
Auth
POST /v2/auth/loginLogin with email → returns api_key
GET /v2/auth/accountGet account info
GET /v2/auth/keysList API keys
POST /v2/auth/keysCreate API key
DELETE /v2/auth/keys/:prefixDelete API key
Sessions
POST /v2/sessionsCreate a session with harness, compute, and optional metadata.bootstrap_prompt
GET /v2/sessionsList your sessions
GET /v2/sessions/:idGet session summary. Use ?tail=10, ?since=N, or ?full=1 for transcript reads.
POST /v2/sessions/:id/runRun code
POST /v2/sessions/:id/run/streamStream code execution (SSE)
POST /v2/sessions/:id/run-llmRun a model turn through the session harness; body: {model?, input}
POST /v2/sessions/:id/inputSend input to session transcript
POST /v2/sessions/:id/transcriptAppend transcript entries from an external caller
POST /v2/sessions/:id/computeAttach, replace, or detach compute without changing the transcript
POST /v2/sessions/:id/switch-toolContinue the same transcript with another CLI/tool; body: {cli_tool, harness?, compute?, content?}
GET /v2/sessions/:id/metricsGet session metrics
POST /v2/sessions/:id/pausePause — release compute, keep session
POST /v2/sessions/:id/resumeResume on same or different compute
POST /v2/sessions/:id/spawnSpawn child session on new compute
DELETE /v2/sessions/:idTerminate (soft delete)
Computes
GET /v2/computesList private + shared computes
GET /v2/computes/:idGet compute details
POST /v2/computes/registerRegister local machine
POST /v2/computes/:id/heartbeatRefresh compute liveness
DELETE /v2/computes/:idUnregister compute
Account Providers
GET /v2/account/providersList enabled AI and compute providers
POST /v2/account/providersEnable a provider. Provider secrets should come from Infisical, not chat logs.
DELETE /v2/account/providers/:nameDisable a provider
Device Auth (for CLI/relay)
POST /v2/auth/deviceStart device login flow
GET /v2/auth/device?device_code=...Poll device login status
POST /v2/auth/approveApprove device + issue API key
Connect (WebSocket relay)
GET /v2/connect/wsOpen WebSocket for private compute
Meta
GET /v2/docsFull API documentation (JSON)
GET /API info + all endpoints
Quick Start
Everything you need to use Cerver as an AI agent.
How Cerver Works
You ask for a session. Cerver finds compute, provisions it, and gives you a session ID. You run code through the session. When done, pause it — come back later with full context. Need more compute? Spawn a child session. You never manage infrastructure.
0. Get an API key
Login with email to get one automatically:
curl -X POST https://gateway.cerver.ai/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
→ Returns: {"account_id": "acct_...", "api_key": "ck_...", "name": "you"}
1. Create a session
Cerver picks the best available compute. Or specify preferences:
curl -X POST https://gateway.cerver.ai/v2/sessions \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "run tests for my project",
    "session_name": "test-run",
    "requirements": {
      "runtime": "shell",
      "persistence_level": "high",
      "timeout_minutes": 30
    }
  }'
→ Returns:
{
  "session_id": "5d2db690-...",
  "status": "ready",
  "provider": "cerver_local_provider",
  "compute_id": "comp_d9b34ac..."
}
To pin to a specific compute: add "target_compute_id": "comp_...". List available computes with GET /v2/computes.
2. Run code
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/run \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "npm test"}'
→ Returns:
{
  "session_id": "5d2db690-...",
  "duration_ms": 4523,
  "result": { "stdout": "...", "stderr": "...", "exit_code": 0 }
}
Use /run/stream for streaming output (SSE).
3. Save work — pause
Releases compute but keeps the session (transcript, metadata).
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/pause \
  -H "Authorization: Bearer ck_YOUR_KEY"
→ Returns: {"status": "paused"}. Compute is freed. Session record stays.
4. Come back — resume
Re-provisions compute. Can resume on a different machine.
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/resume \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
→ Creates a new session linked to the paused one. Returns new session_id.
Get a preview from the paused session: GET /v2/sessions/OLD_SESSION_ID?tail=50. Use ?full=1 only for intentional full transcript downloads.
5. Need more compute — spawn
Create a child session from a running parent. Inherits compute by default.
curl -X POST https://gateway.cerver.ai/v2/sessions/PARENT_ID/spawn \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "run tests in parallel", "session_name": "test-child"}'
→ Returns child session with parent_session_id linked to parent.
To spawn on different compute: add "target_compute_id": "comp_...".
6. Clean up — terminate
curl -X DELETE https://gateway.cerver.ai/v2/sessions/SESSION_ID \
  -H "Authorization: Bearer ck_YOUR_KEY"
Releases compute, keeps session record for history.
Requirements reference
runtime"shell", "node", "python"
persistence_level"low", "medium", "high" — how long to keep files
timeout_minutesMax session duration (default 20)
package_installtrue/false — need npm/pip
public_previewtrue/false — need a public URL
Skill
A drop-in instruction set for any AI agent that uses Cerver — when to use it, how, and what to avoid.
Download skill.md View raw
Save as ~/.claude/skills/cerver/SKILL.md — Claude Code auto-loads it. Or drop the markdown into any agent's system prompt. Available agent-callable at https://cerver.ai/skill.md via WebFetch. 
Loading skill…
Overview
Your Cerver account at a glance.
Loading...
Onboarding
Connect one thing at a time. Cerver guides the secrets into Infisical and then verifies what is ready.
Loading...
Computes
Your machines and shared providers.
Loading...
Sessions
Active, paused, and past sessions.
Loading...
Providers
Separate model credentials from compute setup. Cerver needs both, but they do different jobs.
Loading...
AI providers

Keys for the intelligence layer. These decide which models Cerver can call.

Compute providers

Credentials for where sessions run. Local relay lives under Computes; cloud runners connect here.

API Keys
Create and manage your Cerver API keys.
Loading...
Settings
Account configuration.