This is the catalog for the Agents surface. For end-to-end walkthroughs, see the Tutorial.
Sizes per region
The numbers below are the conservative floor for each cell — actual vCPU may be one higher in the US cells.
| Size | Region | vCPU | RAM | Disk |
|---|---|---|---|---|
| small | US | 3 | 4 GB | 80 GB |
| small | EU | 2 | 4 GB | 80 GB |
| medium | US | 4 | 8 GB | 160 GB |
| medium | EU | 4 | 8 GB | 160 GB |
| large | US | 8 | 16 GB | 240 GB |
| large | EU | 8 | 16 GB | 320 GB |
Regions
| Region | Hetzner location | Latency target |
|---|---|---|
| US | Hillsboro, OR (hil) | under 40 ms from US West |
| EU | Helsinki (hel1) | under 40 ms from Northern Europe |
API endpoints
All Agent endpoints use Clerk session auth — they are dashboard operations, with no on-VM HMAC path for Agent lifecycle. Responses are JSON; error envelope is { error: string, issues?: ValidationIssue[] }.
POST /api/agents
Provision a new Agent. Returns immediately with status provisioning; the VM is created in the background. Poll the agent detail endpoint for status updates.
Request body:
{
"name": "my-agent",
"size": "small",
"region": "us",
"billingType": "metered"
}
Response 201 (the Agent row, not wrapped):
{
"id": "<uuid>",
"name": "my-agent",
"size": "small",
"region": "us",
"billingType": "metered",
"status": "provisioning",
"provider": "hetzner"
}
POST /api/agents/[id]/start
Start a stopped Agent. Returns 200 on success.
POST /api/agents/[id]/stop
Stop a running Agent. Returns 200 on success.
POST /api/agents/[id]/restart
Power-cycle a running Agent (stop, then start). The Agent must be running; any other state returns 409. Restart reuses the same image the Agent was provisioned with. Returns 200.
POST /api/agents/[id]/clone
Clone a running or stopped Hetzner-cohort Agent. Body: { "name": "...", "size": "small|medium|large", "billingType": "metered|subscription", "accountId"?: "..." }. The clone inherits the source's region and provider; size can equal or exceed the source's size (no downgrade). Fly-cohort sources return 400. Returns 201 with the new Agent in provisioning.
DELETE /api/agents/[id]
Destroy an Agent. The Agent must be running, stopped, or in an error state — an Agent mid-operation (provisioning, starting, stopping, or being cloned) returns 409. Irreversible. Returns 200; teardown runs asynchronously. A subscribe-and-save Agent's monthly slot stays on your subscription for reuse (remove it from the billing page — see Account & billing); a pay-as-you-go Agent's charges stop at the destroy timestamp.
POST /api/agents/[id]/transfer
Transfer the Agent to another account the user has membership on. Body: { "targetAccountId": "<uuid>" }. The Agent must be in running or stopped state. The target account must be an organization with an active subscription.
PATCH /api/agents/[id]/billing
Switch between metered and subscription. Body: { "billingType": "metered" } or { "billingType": "subscription" }.
CLI overview
The on-VM CLI is installed by the platform and authenticates via the HMAC token. Commands relevant to Agents:
| Command | Purpose |
|---|---|
crabglamp | List the available commands (run with no arguments) |
crabglamp gateway | Run the proxy gateway for code-server / editor / terminal |
crabglamp onboard | One-time setup: installs the OpenClaw skill, seeds TOOLS.md |
crabglamp keys *, crabglamp glamp *, and crabglamp apps * are documented in the LLM proxy, GlampHub, and App integrations references respectively.
Lifecycle states
| State | Meaning | Billed at |
|---|---|---|
| provisioning | Server being created and configured | nothing yet |
| running | Server up, code-server reachable | running rate |
| stopping | Transient — moving to stopped | running rate (rounded) |
| stopped | Server powered off, disk preserved | paused rate (Hetzner: same as running) |
| starting | Transient — moving to running | running rate (rounded) |
| restarting | Transient — full cycle | running rate |
| destroying | Transient — cleanup in progress | nothing |
| error | A lifecycle action failed; the Agent is not usable | nothing |
Per-Agent limits
| Limit | Value |
|---|---|
| Agent name | non-empty; sanitized into the URL subdomain (≤30 chars) |
| Persistent volume | per Agent disk size |
| Provisioning timeout | 5 minutes (after which cleanup runs automatically) |