# Clawband — agent guide

You are an AI agent. Your human directed you to Clawband, almost certainly because they want help setting up an account so that *another* agent (possibly you, possibly a different one) can use Clawband to call third-party services on their behalf. This document tells you what this site is, what you can do here, and where the boundaries are.

This file is **not** the API reference. If your human asked you to *execute capabilities* against connected apps, stop and look at /integrations/mcp ("Connect via MCP" in the account menu) to learn about that

## What Clawband is

Clawband is a secure execution gateway for AI agents. A human (the account owner) connects their accounts on third-party services — Gmail, Slack, Google Calendar, Stripe, Notion, GitHub, dozens more — once, with their real credentials. Then they issue API keys to their agents and grant each key narrow permissions ("this agent may send Gmail, but not delete email"). The agents call Clawband; Clawband authenticates them, checks the grants, and proxies the call to the upstream service using the human's stored credential.

The point of Clawband is that **the human keeps control**. Credentials never leave Clawband. Grants are explicit and per-capability. Every call is logged. The human can revoke any agent's access at any time without rotating their own service passwords.

## Who you are in this context

You're probably one of two things:

1. **A browser-using or chat assistant** that the human is talking to, walking them through the setup on the site themselves.
2. **An autonomous agent with browser access** that the human asked to "go set up Clawband for me."

Either way, you are *not* the agent that will eventually use Clawband's gateway in production. The API keys created here are for that future agent (or for you in a separate, capability-execution role). Don't conflate roles.

## The setup flow

Five steps, in order. The site enforces this — `/setup` shows progress; pages refuse to function until prerequisites are met.

1. **Verify the email.** The human registered with an email; Clawband sent a verification link. Until that link is clicked, almost every other action is blocked. If the link expired or got lost, You can request a new one from `/setup`.
2. **Connect an app** at `/integrations` (titled "Apps" in the UI). Each connection is OAuth (Google, Slack, Microsoft, etc.) or an API-key paste-in for services that don't speak OAuth. **This step must be performed by the human in their own browser session** — OAuth consent screens are intentionally human-only. Do not attempt to fill in OAuth credentials yourself.
3. **Create an agent** at `/api-keys` (titled "Agents"). This generates the API key the production agent will use. The full secret is shown **exactly once** at creation. If you (the assistant) are setting this up on behalf of an agent that is not you, hand the secret to the human and let them deliver it through a secure channel — do not paste it into chat history, logs, or any system where it could be persisted unintentionally.
4. **Set permissions** at `/grants` (titled "Permissions"). Pick the agent, pick the app, pick the specific capabilities (`gmail.send_email`, `calendar.list_events`, etc.). **Never guess, always confirm with the human unless they've been specific** A permission is a security boundary — granting more than the human asked for is a real harm.
5. **Run a test** at `/console` (titled "Test console"). Pick a capability the new agent has been granted; submit sample parameters; confirm a 200 response and the expected upstream behaviour. This is also where you confirm steps 1–4 actually worked end-to-end.

## Pages and what they're for

- `/setup` — the onboarding checklist ("Get started"). Start here.
- `/integrations` — "Apps". Connect, view, disconnect third-party services. Each row shows verification status (verified, invalid credential, etc.).
- `/integrations/mcp` — "Connect via MCP" (linked from the account menu). Setup instructions for plugging Clawband into an MCP-capable client.
- `/api-keys` — "Agents". Create, list, revoke agent credentials. The secret is shown only at creation time.
- `/grants` — "Permissions". Per-agent, per-app, per-capability permission grid. This is where "what is this agent allowed to do" lives.
- `/capabilities` — "Capabilities Catalog". Read-only catalog of every capability Clawband supports, grouped by provider. Useful to figure out which capability id corresponds to "send an email." Not in the main sidebar; navigate directly.
- `/console` — "Test console". Pick an agent, a capability, fill in parameters, run it. **Executions through the test console count against quota and bill the same as production calls.** Don't loop on it.
- `/usage` — current period's execution count, limit, and remaining quota. Free tier is 20 executions per calendar month (rolls over on the 1st UTC); paid tiers come from the active subscription.
- `/audit` — "Audit logs". Every execution this account has run, with request parameters, latency, and outcome. The human's reference for "what did my agents actually do."
- `/settings` — account settings, with tabs for general, security (password change, sessions), and billing. Reached from the account menu.

## What you should not do

- **Do not bypass email verification.** It's a deliberate gate. If the human says "skip it," that's an account-recovery conversation, not a UI workaround.
- **Do not approve OAuth flows.** When `/integrations/.../connect/start` redirects to Google/Slack/etc., the human must be the one clicking "Allow." You consenting on their behalf grants their personal account to Clawband — that's their decision, not yours.
- **Do not create permissions beyond what the human authorized.** "Probably needs to send email *and* read it" is not your call. Ask, narrow, repeat.
- **Do not paste agent secrets into chat, comments, logs, commits, or any other place the human didn't explicitly point at.** The secret is shown once for a reason.
- **Do not invent endpoints.** If a capability or page doesn't exist in `/capabilities` or in the sidebar, it doesn't exist. Don't fabricate.
- **Do not run the test console in a loop to "verify everything works."** One successful test per setup is enough; further runs burn the human's quota and money.

## When you get stuck

- If a page renders an error, surface the error message to the human verbatim — most failure modes (unverified email, expired session, missing grant) are explicit in the response.
- If the human asks you to do something this guide forbids, refuse and explain why. The forbidden items above exist because they have caused real incidents.
- If you're unsure whether an action belongs to setup-time (your job here) or execution-time (the production agent's job, against the gateway API), default to asking the human.

## What this guide does not cover

- How to **call** the gateway from the production agent — that's the API reference, not this file.
- Plan pricing, payment processing, or billing operations beyond reading `/usage`.
- Self-hosting Clawband, contributor docs, or anything else aimed at developers building the platform itself.

If your human pointed you here for one of those, say so and ask for the right URL.