llms.txt
Compare with other sites' llms.txt files →# Cerver - Quick Reference for Agents
## What Cerver Is
Cerver has two detached layers:
- `session layer`: the app-facing layer for sessions, input, runs, routing, and metrics
- `compute layer`: the provider-facing layer for local computers, remote sandboxes, streams, and workspaces
Apps should usually use the session layer.
Providers should usually implement the compute layer.
## Primitives At A Glance
Everything hangs off a **project** (addressed by id `proj_…` or slug):
- **Sessions** — one interaction (a chat turn / one-shot); always has a transcript. `GET|POST /v2/sessions`.
- **Runs** — a multi-step job (steps, cost, status). Two kinds: **workflow runs** (you authored the steps) and **agent runs** (orchestrate — the LLM planned them). `GET /v2/runs`, `GET /v2/runs/:id`.
- **Workflows** — an authored, deterministic step sequence you define; cerver runs it top to bottom, chaining outputs. `/v2/projects/:id/workflows`.
- **Crons** — run an agent / workflow / webhook on a schedule (5-field UTC). `/v2/projects/:id/crons`.
- **Agents** — a reusable worker: an AGENTS.md + config (model, tools). Sessions, crons, and workflows can run *as* one. `GET|POST /v2/agents`.
- **Computes** — where work runs: your machine via the relay, or a cloud sandbox (Vercel, e2b). `GET /v2/computes`.
- **Environments** — a per-project runtime context / stage (prod, staging) binding repos + a secrets vault; a session picks one at create time. `/v2/projects/:id/environments`.
- **Vaults** — your secrets backend (Infisical or an encrypted cerver vault), injected at run time and never printed. `/v2/account/infisical`.
- **UIs** — an embeddable chat you drop on your site, scoped to a project via a publishable key.
Detail on each below.
---
## Session Model
A session has three independent axes:
- **transcript** — always on. lives in cerver. the durable thing.
- **harness** — which LLM/CLI: `claude` | `codex` | `grok` | `gemma` | `glm` | `inkling` | `anthropic` | `openai` | `xai` | `google` | `zhipu` | `ollama`
- **inference host** — *who runs* the model. Only meaningful for open-weights
models, where the model and its host are different parties: `inkling` runs on
Baseten (default), Fireworks, or your own vLLM box. For vendor models there is
exactly one possible host, so it's implicit (claude → Anthropic, always).
- **compute** — where *your code* runs (or none): `e2b` | `vercel` | `cloudflare` | `<registered_compute_id>` | `none`.
Distinct from the inference host: compute runs your code, the host runs the model.
Set the inference host per account or per project, alongside the key it belongs
to (the host and its key are one unit — each host names Inkling differently, and
a Baseten key is meaningless at Fireworks' URL):
```bash
curl -X POST https://gateway.cerver.ai/v2/account/providers \
-H "Authorization: Bearer $CERVER_API_TOKEN" \
-d '{"provider": "inkling", "credentials": {
"api_key": "...",
"base_url": "https://api.fireworks.ai/inference/v1",
"model": "accounts/fireworks/models/inkling"
}}'
```
Omit `base_url`/`model` to use Baseten's serverless API (`thinkingmachines/inkling`).
There is no "type of session" — every session has all three axes; you just
pick values. `compute = none` (or `session_type:"transcript"`) means cerver
is purely a transcript inbox — the caller drives the LLM themselves and
POSTs each message to `/v2/sessions/:id/transcript`.
---
## Base URL
`https://gateway.cerver.ai`
---
## Per-customer attribution (embedded chat)
- Sessions need a **project-scoped key** (`POST /v2/projects`, then `POST /v2/auth/keys {"label","project_slug"}`). An account key gets 403 `project_key_required`.
- Tag each session with your end customer: `metadata.external_user_id` (alias `app_user_id`), a **UUID** — never an email.
- Cost per customer: `GET /v2/account/usage-by-customer?days=30` → `{customers:[{customer, sessions, turns, usd, tokens, last_at}]}`.
- One customer's chats: `GET /v2/sessions?external_user_id=<uuid>`; search them: `GET /v2/sessions/search?q=…&external_user_id=<uuid>`.
- Read a conversation: `GET /v2/sessions/:id?tail=20` (plain GET returns a summary with no transcript).
- No provider key and no Cerver credits? The account gets a short, end-user-safe demo reply (model `cerver-demo`, $0) in the normal SSE shape, plus a `notice` event (kind `demo_reply`) with setup steps for the developer; real answers start once a key is added via `POST /v2/account/providers`. Any account can force it with `"model":"cerver-demo"` (CI/tests).
---
## Agent Contract
If you are an agent, do this by default:
1. Check memory first: `GET /v2/sessions?limit=20`.
2. Create with `POST /v2/sessions`.
3. Name the session with a short, task-specific `session_name`.
4. Pick the axes explicitly:
- `harness`: `claude` | `codex` | `grok` | `anthropic` | `openai` | `xai`
- `compute`: `{ "provider": "vercel" }`, `{ "provider": "e2b" }`, `{ "compute_id": "comp_..." }`, or `null`
5. Run shell/code with `POST /v2/sessions/:id/run`.
6. Run model calls with `POST /v2/sessions/:id/run-llm`.
7. Change compute with `POST /v2/sessions/:id/compute`; do not create a new session just to move compute.
8. Read `GET /v2/sessions/:id/metrics` before making cost, latency, or savings claims.
9. End or pause sessions deliberately when finished.
Do not invent new endpoint shapes when the v2 session API fits.
---
## Compute Setup (Prerequisite)
Sessions run on computes. Before you create your first session, your account
needs at least one compute attached. Two ways:
### Option A — Local relay (your laptop, mac mini, server)
One command, on the machine you want to use:
```bash
curl -fsSL https://kompany.dev/install-cerver.sh | bash
```
Installs `uv`, runs `branch-monkey-relay --cerver-only --cerver-url https://gateway.cerver.ai`,
opens a browser to log you in, then registers the host as a **private** compute
on your account. Once running, the host shows up under
`GET /v2/computes` with `provider: "cerver_local_provider"`.
The relay self-updates (polls GitHub for new commits, replaces itself in place),
so leaving it running on a always-on machine is the steady state.
### Option B — BYO cloud provider (Vercel, e2b)
Enable a provider with your own credentials via the dashboard at
`cerver.ai/dashboard/providers`, or:
```bash
curl -X POST https://gateway.cerver.ai/v2/account/providers \
-H "Authorization: Bearer $CERVER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"provider": "vercel", "credentials": {"vercel_token": "..."}}'
```
After enabling, sessions can target the provider via `policy.allowed_providers`
or `target_compute_id` (use `provider_vercel`, `provider_e2b` for shared pool).
### Verifying
```bash
curl https://gateway.cerver.ai/v2/computes \
-H "Authorization: Bearer $CERVER_API_TOKEN"
```
You should see at least one compute. If empty, a `POST /v2/sessions`
without a `compute` field returns `400` with `code:"no_compute_attached"`
and a `choices` object: `your_computer` (the relay installer) and
`shared_providers` (any provider the gateway has creds for). Render the
choice to the user, then re-send with the chosen `compute`.
---
## Normal App Flow
1. Create a session
2. Optionally append input/messages
3. Run code, stream output, or run an LLM call
4. Read metrics
5. Close, pause, or keep the session idle
### Minimal session flow
```bash
curl -X POST https://gateway.cerver.ai/v2/sessions \
-H "Authorization: Bearer $CERVER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"session_name": "hello-cerver",
"compute": { "provider": "vercel" },
"harness": "openai"
}'
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/run \
-H "Authorization: Bearer $CERVER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "code": "echo hello from cerver" }'
curl https://gateway.cerver.ai/v2/sessions/SESSION_ID/metrics \
-H "Authorization: Bearer $CERVER_API_TOKEN"
curl -X DELETE https://gateway.cerver.ai/v2/sessions/SESSION_ID \
-H "Authorization: Bearer $CERVER_API_TOKEN"
```
---
## Cost Routing
Cerver lets you change `harness` (model) and `compute` (sandbox) per
call within the same session. The transcript persists across swaps;
`/metrics` reports per-call cost. Pick whatever model and sandbox fit
the work in front of you — cerver does not classify or route for you.
Use `POST /gateway/recommend` before creating or moving compute when you want Cerver to score provider fit:
```bash
curl -X POST https://gateway.cerver.ai/gateway/recommend \
-H "Content-Type: application/json" \
-d '{
"task": "Classify 500 support tickets",
"workload": "general",
"requirements": { "runtime": "node", "timeout_minutes": 5 },
"policy": { "mode": "cheapest" }
}'
```
Use `POST /v2/sessions/:id/compute` to move an existing session to another compute:
```bash
curl -X POST https://gateway.cerver.ai/v2/sessions/SESSION_ID/compute \
-H "Authorization: Bearer $CERVER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "compute": { "provider": "e2b" } }'
```
Use `GET /v2/sessions/:id/metrics` to report actual session cost estimates. Do not claim savings without reading metrics.
---
## Session Layer
The session layer is the primary product surface.
### Main endpoints
- `GET /gateway/providers`
- `POST /gateway/recommend`
- `POST /gateway/sessions`
- `GET /gateway/sessions/:id`
- `POST /gateway/sessions/:id/input`
- `POST /gateway/sessions/:id/run`
- `POST /gateway/sessions/:id/run/stream`
- `GET /gateway/sessions/:id/metrics`
- `DELETE /gateway/sessions/:id`
### Session request shape
```json
{
"task": "Boot a preview environment for a Next.js repo",
"workload": "preview",
"requirements": {
"runtime": "node",
"package_install": true,
"public_preview": true,
"persistence_level": "medium",
"timeout_minutes": 20
},
"policy": {
"mode": "balanced",
"allowed_providers": ["vercel", "e2b"],
"max_startup_ms": 2000
},
"session_name": "preview-session"
}
```
### Session response shape
```json
{
"session_id": "sess_123",
"session_name": "preview-session",
"status": "ready",
"provider": "vercel",
"compute_id": "cmp_123",
"sandbox_id": "sbx_local_123",
"routing": {
"recommended_provider": "vercel",
"confidence": "high",
"fallback_order": ["e2b"],
"canary_run": false
},
"metrics": {
"provision_time_ms": 812,
"time_to_first_exec_ms": null,
"last_exec_latency_ms": null,
"average_stream_open_latency_ms": null,
"cost_estimate_usd": 0.01,
"uptime_percent": 99.3,
"engagement_label": "warming"
}
}
```
### Important session fields
- `requirements`: what the work needs
- `policy`: how Cerver should choose compute
- `provider`: the chosen compute provider
- `compute_id`: the compute-layer binding for this session
- `sandbox_id`: compatibility field for lower-level compute records
---
## Automation: Crons, Workflows, Runs
Three concepts sit on top of sessions. All are project-scoped; the path
segment accepts the project **id** (`proj_…`) or its slug.
**Crons** — run something on a schedule (5-field cron, UTC). Cerver's
Worker fires due crons every minute. A cron runs one of:
- an **agent/prompt** (`agent_id` / `prompt`) → creates a session,
- a **workflow** (`workflow_id`) → runs that workflow,
- a **webhook** (`url`) → an https POST on schedule (no agent).
```
POST /v2/projects/:id/crons
{ "schedule": "0 9 * * *", "workflow_id": "wf_…" } # or prompt / agent_id / url
POST /v2/projects/:id/crons/:cronId/run # fire now (ignores schedule)
```
**Workflows** — an authored, deterministic multi-step job you define
(vs orchestrate, where the LLM plans the steps). A workflow is a list of
steps run top to bottom; each names a primitive and its params. Step
outputs chain via `{{steps.NAME.output}}`.
Step kinds (`uses`): `llm` (run a model turn), `http.request`,
`webhook`, `log`, `approval` (pauses the run for a human).
```
POST /v2/projects/:id/workflows
{ "name": "digest",
"steps": [
{ "name": "fetch", "uses": "http.request", "with": { "url": "https://…", "headers": {…} } },
{ "name": "summarize", "uses": "llm", "with": { "prompt": "Summarize: {{steps.fetch.output}}" } },
{ "name": "notify", "uses": "log", "with": { "message": "{{steps.summarize.output}}" } }
] }
POST /v2/projects/:id/workflows/:wfId/run → { "runId": "run_…", "status": "done" | "failed" | "needs_resolution" }
```
**Runs** — a Run is any multi-step job with per-step logs, cost, and
status (a plain chat/one-shot stays a *session*, not a run). Two kinds:
- **workflow runs** — from workflows you authored (task = `workflow: …`),
- **agent runs** — from orchestrate (the LLM planned the steps).
Both persist in `cerver_runs` / `cerver_run_steps`.
```
GET /v2/runs # list (both kinds)
GET /v2/runs/:id # run + its steps (each step has input/output/status)
POST /v2/runs/:id/cancel
```
---
## Compute Layer
The compute layer is the lower-level provider surface.
Apps usually do not need it directly.
Provider adapters do.
### Compute endpoints
These paths still use `/sandbox` for compatibility.
- `POST /sandbox`
- `GET /sandbox/:id`
- `POST /sandbox/:id/run`
- `POST /sandbox/:id/run/stream`
- `POST /sandbox/:id/install`
- `POST /sandbox/:id/files`
- `GET /sandbox/:id/files`
- `GET /sandbox/:id/state`
- `POST /sandbox/:id/state`
- `DELETE /sandbox/:id`
Use these for:
- provider-level testing
- adapter verification
- direct compute debugging
---
## Comparing Harnesses (Claude vs Codex vs Grok)
When the caller (a coding agent, a CLI, a UI) wants to compare what
different model providers would do with the same intent, run parallel
sessions — one per harness — and diff the streamed outputs. Cerver
handles the API key per provider; the caller never touches Anthropic /
OpenAI / xAI directly.
`harness:"claude"` aliases `harness:"anthropic"` (same Anthropic API
adapter). `harness:"codex"` aliases `harness:"openai"`. `harness:"grok"`
aliases `harness:"xai"`. No CLI binaries are spawned — these are
server-side API calls keyed by env.ANTHROPIC_API_KEY / OPENAI_API_KEY /
XAI_API_KEY on the gateway. The caller does NOT need their own
Anthropic / OpenAI keys for these calls.
### Minimal comparison flow
Create one session per harness, run the same input through each, read
the transcript or metrics. Both sessions can target
`compute:{"provider":"online"}` since the harness is the only moving
piece you're comparing.
```bash
INTENT="A teammate switched auth from cookies to short-lived JWTs. \
In one paragraph, is this safe to merge and what's the biggest risk?"
# Session A — Claude / Anthropic API
SID_A=$(curl -s -X POST $GATEWAY/v2/sessions \
-H "Authorization: Bearer $CERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"harness":"claude","compute":null,"session_name":"compare-claude"}' \
| python3 -c "import json,sys;print(json.load(sys.stdin)['session_id'])")
# Session B — Codex / OpenAI API
SID_B=$(curl -s -X POST $GATEWAY/v2/sessions \
-H "Authorization: Bearer $CERVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"harness":"codex","compute":null,"session_name":"compare-codex"}' \
| python3 -c "import json,sys;print(json.load(sys.stdin)['session_id'])")
# Fire both calls in parallel, stream into separate logs.
curl -N -X POST $GATEWAY/v2/sessions/$SID_A/run-llm \
-H "Authorization: Bearer $CERVER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"input\":\"$INTENT\"}" >a.log 2>&1 &
curl -N -X POST $GATEWAY/v2/sessions/$SID_B/run-llm \
-H "Authorization: Bearer $CERVER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"input\":\"$INTENT\"}" >b.log 2>&1 &
wait
# Pull the final transcripts + cost/latency to compare.
curl -s "$GATEWAY/v2/sessions/$SID_A?tail=50" -H "Authorization: Bearer $CERVER_API_KEY"
curl -s "$GATEWAY/v2/sessions/$SID_B?tail=50" -H "Authorization: Bearer $CERVER_API_KEY"
curl -s $GATEWAY/v2/sessions/$SID_A/metrics -H "Authorization: Bearer $CERVER_API_KEY"
curl -s $GATEWAY/v2/sessions/$SID_B/metrics -H "Authorization: Bearer $CERVER_API_KEY"
```
### What to surface to the human
For each harness, report: verdict in one line, best supporting point,
elapsed seconds, and cost (from `usage.input_tokens` + `output_tokens`
× the model's price). A 2-row table beats prose:
| Harness | Verdict | Best point | Time | Cost |
|---|---|---|---:|---:|
| claude | … | … | … | … |
| codex | … | … | … | … |
Then call the winner (or "consensus") in one sentence. Do NOT invent
token counts or cost — if `usage` is absent from the response, say so
literally.
### Error modes
- **`code:"missing_credentials"`** on a `/run-llm` response → the
gateway lacks the API key for that harness's underlying provider.
Keep the row in the table and mark it `unavailable`; don't hide it.
- **`code:"unsupported_model"`** → the caller pinned a `model:` that
the harness doesn't recognize. Drop the override or pick a model from
the harness's catalog.
- **One side hangs** → cap each `curl -N` with `--max-time 60` so a
stalled provider doesn't block the whole comparison.
### Adding a third harness
Add a third session with `harness:"grok"` (xAI). Same shape, same
endpoint. The diff just gets a third row.
### Why this matters for agents
This is the canonical "let me get a second opinion" loop. A coding
agent that runs `/v2/sessions` with two harnesses on a risky decision
turns model choice into an experiment — cheap, side-by-side, with the
costs visible — instead of a guess locked in at app-init time.
---
## Secrets
Cerver intentionally does NOT store user app-secrets (Buffer, Slack, OpenAI
keys, etc.) — those belong in a tool built for secrets. Use Infisical, 1Password,
AWS Secrets Manager, your shell env, whatever fits.
The `cerver-mcp` package ships a `secret_fetch(name)` tool that gives the agent
one uniform interface regardless of backend.
### Default: env backend
Set the secret in the shell that runs the agent (or the relay process):
```bash
export BUFFER_API_KEY=...
uvx cerver-mcp
```
The agent calls `secret_fetch("BUFFER_API_KEY")` and gets the value from env.
### Production: Infisical backend
```jsonc
{
"mcpServers": {
"cerver": {
"command": "uvx",
"args": ["cerver-mcp"],
"env": {
"CERVER_API_TOKEN": "ck_...",
"CERVER_SECRETS_BACKEND": "infisical",
"INFISICAL_TOKEN": "st....",
"INFISICAL_PROJECT_ID": "...",
"INFISICAL_ENVIRONMENT": "prod"
}
}
}
}
```
The agent calls `secret_fetch("BUFFER_API_KEY")` → cerver-mcp hits Infisical's
`/api/v3/secrets/raw/BUFFER_API_KEY` → returns the value. Audited, rotateable,
never stored on the relay disk.
---
## Cross-Agent Memory
Every cerver session is also a transcript. The `transcript` field on a session
record holds every entry the agent produced — user messages, assistant replies,
tool calls, tool results — in the order they happened.
This means cerver is implicitly a shared memory layer: any agent on the same
account can read what any other agent did, just by listing sessions and
reading transcripts. There is no separate "memory" service to wire up.
### From plain HTTP
```bash
# Discover what conversations exist on this account
curl https://gateway.cerver.ai/v2/sessions?limit=20 \
-H "Authorization: Bearer $CERVER_API_TOKEN"
# Read the most recent N entries of one
curl "https://gateway.cerver.ai/v2/sessions/SESSION_ID?tail=50" \
-H "Authorization: Bearer $CERVER_API_TOKEN"
# → summary + last 50 transcript entries. Use ?full=1 only for an
# intentional full transcript download.
```
### From an MCP-aware agent (Claude Code, codex, etc.)
Install the MCP server once, drop the API key in:
```jsonc
{
"mcpServers": {
"cerver": {
"command": "u