Source: https://crabglamp.com/docs/agents/reference
Last updated: 2026-06-11
Type: reference

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:

```json
{
  "name": "my-agent",
  "size": "small",
  "region": "us",
  "billingType": "metered"
}
```

Response 201 (the Agent row, not wrapped):

```json
{
  "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](/docs/account-and-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:

<table>
  <thead>
    <tr><th>Command</th><th>Purpose</th></tr>
  </thead>
  <tbody>
    <tr><td><code>crabglamp</code></td><td>List the available commands (run with no arguments)</td></tr>
    <tr><td><code>crabglamp gateway</code></td><td>Run the proxy gateway for code-server / editor / terminal</td></tr>
    <tr><td><code>crabglamp onboard</code></td><td>One-time setup: installs the OpenClaw skill, seeds <code>TOOLS.md</code></td></tr>
  </tbody>
</table>

`crabglamp keys *`, `crabglamp glamp *`, and `crabglamp apps *` are documented in the LLM proxy, GlampHub, and App integrations references respectively.

## Lifecycle states

<table>
  <thead>
    <tr><th>State</th><th>Meaning</th><th>Billed at</th></tr>
  </thead>
  <tbody>
    <tr><td>provisioning</td><td>Server being created and configured</td><td>nothing yet</td></tr>
    <tr><td>running</td><td>Server up, code-server reachable</td><td>running rate</td></tr>
    <tr><td>stopping</td><td>Transient — moving to stopped</td><td>running rate (rounded)</td></tr>
    <tr><td>stopped</td><td>Server powered off, disk preserved</td><td>paused rate (Hetzner: same as running)</td></tr>
    <tr><td>starting</td><td>Transient — moving to running</td><td>running rate (rounded)</td></tr>
    <tr><td>restarting</td><td>Transient — full cycle</td><td>running rate</td></tr>
    <tr><td>destroying</td><td>Transient — cleanup in progress</td><td>nothing</td></tr>
    <tr><td>error</td><td>A lifecycle action failed; the Agent is not usable</td><td>nothing</td></tr>
  </tbody>
</table>

## Per-Agent limits

<table>
  <thead>
    <tr><th>Limit</th><th>Value</th></tr>
  </thead>
  <tbody>
    <tr><td>Agent name</td><td>non-empty; sanitized into the URL subdomain (≤30 chars)</td></tr>
    <tr><td>Persistent volume</td><td>per Agent disk size</td></tr>
    <tr><td>Provisioning timeout</td><td>5 minutes (after which cleanup runs automatically)</td></tr>
  </tbody>
</table>