---
name: clawmetry-agent-builder
description: Create, message, and manage always-on hosted AI agents on ClawMetry Agent Builder via its REST API. Use when the user wants to deploy a hosted agent (claude_code, openclaw, hermes, picoclaw, ...) programmatically, send it messages, read its activity, connect Telegram, or pause/destroy it without the web UI.
---

# ClawMetry Agent Builder — Agent API

Base URL: `https://build.clawmetry.com`

## Auth

Every authenticated call sends `Authorization: Bearer cmak_...`.
The user creates a key at https://build.clawmetry.com/developers (sign in → Generate key).
Ask the user for their key (suggest they export it as `CLAWMETRY_API_KEY`);
never guess or fabricate one. Creating agents charges the account's credit
balance, so confirm price with the user before `POST /api/provision`.

## Discover runtimes (no auth)

```bash
curl -s https://build.clawmetry.com/api/runtimes
```

Returns hostable runtimes with `id`, monthly `price_cents_month`, `channels`,
and `included_model` (true = works with zero API-key setup on the metered
included plan).

## Create an agent

```bash
curl -s -X POST https://build.clawmetry.com/api/provision \
  -H "Authorization: Bearer $CLAWMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runtime": "claude_code",
       "brief": "Watch my GitHub issues and draft replies. Be concise.",
       "model_mode": "managed"}'
```

- `runtime`: an id from `/api/runtimes`.
- `brief`: plain-language standing instructions; becomes the agent's memory.
- `model_mode`: `managed` (included metered model, default) or `byok`
  (add your own key afterwards via the config endpoint).
- `201` → instance JSON with `id`. `402` → not enough credits (top up at
  https://build.clawmetry.com). `409` → another deploy for this account is still settling.

The first month's plan price is debited immediately — except the account's
first-ever agent, whose first month is free (renewals at plan price).
Boot takes ~1-2 minutes; poll `GET /api/instances/<id>` until
`"status": "running"`.

## Talk to it

```bash
curl -s -X POST https://build.clawmetry.com/api/instances/<id>/messages \
  -H "Authorization: Bearer $CLAWMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 910 \
  -d '{"text": "Summarize what you can do."}'
```

Synchronous: the reply comes back in this response. Long agent turns can take
minutes (hard cap 900s) — always set a long client timeout. One turn runs at
a time per agent (concurrent calls queue). `409` = agent not running.

## Everything else

```
GET  /api/instances                     list your agents
GET  /api/instances/<id>                status, config flags, brief
GET  /api/instances/<id>/activity       recent turns + credit charges
POST /api/instances/<id>/config         {"agent_brief": ..., "ANTHROPIC_API_KEY": ...,
                                         "TELEGRAM_BOT_TOKEN": ..., "model": ...}
                                        (restarts the agent to apply)
POST /api/instances/<id>/pause          stop the machine
POST /api/instances/<id>/resume         start it again
POST /api/instances/<id>/destroy        permanent; unused hosting refunded.
                                        Confirm with the user first.
```

All lifecycle calls return `{"ok": true, ...}` or `{"error": "..."}` with a
meaningful HTTP status (401 bad key, 404 not yours, 409 wrong state,
402 needs top-up).

## MCP instead of curl

The same capabilities are exposed as an MCP server:

```bash
claude mcp add --transport http clawmetry https://build.clawmetry.com/mcp \
  --header "Authorization: Bearer $CLAWMETRY_API_KEY"
```