---
title: "docs"
canonical_url: "https://superbot.gg/docs"
last_updated: "2026-09-25"
summary: "how the superbot app works: get the app, add the Helper and its CLI, and see what each feature of the agent manager does."
---

> Markdown twin of https://superbot.gg/docs (the HTML page is canonical).
> The site index for agents is /llms.txt; every content page has a twin at its path plus `.md`.

[superbot.gg](https://superbot.gg/) / docs

# Docs

superbot manages the AI agents you already use. The app runs them on the vendor accounts you already pay for, and the Helper keeps those accounts sealed on your own machine.

## Start here

Most people start with the app. All three ways in end at the same account, the same agents and the same spend.

### Get the app

The desktop app is where you manage your agents: chats, projects and swarms on your own vendor accounts. The phone app is the same account.

[Get early access](https://superbot.gg/invite?step=signin&next=/download) [About the phone app](https://superbot.gg/docs#apps)

### Install the Helper and CLI

One line installs the Helper, the `superbot` CLI with it, then the desktop app. The Helper wires every AI client it finds on this machine.

[Get early access](https://superbot.gg/invite?step=signin&next=/docs%23install)

### Call the API

Mint a caller key and point any OpenAI- or Anthropic-shaped client at this origin.

`curl https://superbot.gg/v1/models -H "Authorization: Bearer sbc_…"`

[Mint a caller key](https://superbot.gg/docs#api-auth) [Every endpoint](https://superbot.gg/docs#api-endpoints)

### Install

The app from the [download page](https://superbot.gg/download) is the whole install for most people. The line above is the terminal path: it installs the Helper, registers it to start at login and wires the AI clients it finds, then installs the desktop app. For the Helper and CLI alone, add `--no-app`, or `-NoApp` on Windows. Running the same line again is the update.

Nothing here touches node, npm or your shell's rc files: the Helper ships as one signed binary, from Homebrew when it is on your PATH, else a direct download verified against a checksum before it runs. An install that fails partway is safe to re-run, or add `--force`. Rather connect one client straight to the MCP server? See [MCP server and the superbot tool](https://superbot.gg/docs#tool).

### Verify

Open the app and sign in. Then restart an AI client the Helper wired and ask it what superbot tools it has. You should see one tool, `superbot`. Running it may ask you to pair once, which ties this device to your account.

Checking the server from this browser…

`what superbot tools do you have?`

### Your connection

Live from this origin. Nothing here is a sample.

MCP endpoint

`https://superbot.gg/mcp`

API base

`https://superbot.gg/v1`

Models you can dial

`superbot, superbot-omni, superbot-fast`

Rate limit

1200 requests a minute per key

Sign in to see your caller keys. [Sign in](https://superbot.gg/login?then=/docs), or mint one at [Caller keys](https://superbot.gg/account/api#keys).

## Features

What superbot does, one section each: what it is, how to use it, and one thing to try.

### Desktop and phone apps

The desktop app is superbot itself: one window for every agent you run, on the vendor accounts you already pay for. Sign in on the desktop and the phone with the same email and both resolve to one account: one balance, one history, one set of projects. A session you start on the phone keeps going on the desktop.

#### How to use it

1. Download the app from the [download page](https://superbot.gg/download) on each device and sign in with the same email.
2. Keep working across them. A chat, a project and its rules and skills are the same on both, because they are the same account.
3. Turn sync on or off in Settings, under **Sync projects across devices**.

Chats, projects, rules, skills, context, MCP servers and settings sync between your devices. Changes push live, and a poll catches the rest. Recently used folders sync encrypted. **Sync now** on a project pushes it straight away.

Credentials the Helper can reach sync across all your devices by default, including browser cookies and sessions, saved passwords, SSH keys, OAuth and vendor credentials, and MCP binding tokens. Only an explicit decline in Settings withholds a class.

#### Try it

Start a chat on the phone, then open the desktop app: the thread is waiting with its context. The same works the other way.

[Download the apps](https://superbot.gg/download) [Account](https://superbot.gg/account)

### The Helper, the CLI and the local relay

The Helper is the small daemon that runs on your own machine. It pairs the machine to your account once, then serves a local relay at `http://127.0.0.1:18787/mcp` that your AI clients dial, holding your own vendor credentials sealed on the device.

#### How to use it

The Helper is the part that stays local. It routes the clients it finds, keeps your vendor accounts sealed, and answers on loopback, so a client on the machine reaches the tool without a public address. The hosted edge is the other side: it holds the adapters, the swarm router, the routine scheduler and the imported-chat store.

1. Sign in and pair the machine once with `superbot signin`, which opens your browser.
2. Point a local MCP client at `http://127.0.0.1:18787/mcp`.
3. Check what the Helper is doing with `superbot status`, and open a session with `superbot chat`.
4. Update the Helper alone with `superbot update`.

The same binary answers to `superbot` on your PATH. Its verbs are `status`, `accounts`, `clients`, `keys`, `mcp`, `sync`, `meter`, `relay`, `pair`, `signin`, `chat`, `session`, `helper`, `update`, `cookies` and `uninstall`, each as `superbot <verb>`. Run it with no verb at all in a terminal and it opens a chat session.

#### Try it

Open a session in a terminal, then see what the Helper is up to:

`superbot chat`

`superbot status`

Seal one site's browser session with `superbot cookies <domain>`. The desktop app carries the app's own update; `superbot update` updates the Helper alone. To remove everything, `superbot uninstall` deletes the Helper, the app and superbot's entries in your AI clients after it asks, and `superbot uninstall --dry-run` lists what would go without deleting it.

[Download the Helper and apps](https://superbot.gg/download) [Account](https://superbot.gg/account)

### Your AI clients

superbot manages the AI clients you already use, Claude Code, Cursor, Codex and the rest, and never replaces them. The Helper finds them on your machine and routes each one through your account, so every client shares the same agents, context and spend.

#### How to use it

1. Install the app, or run the Helper line from [Start here](https://superbot.gg/docs#start). Either way the Helper lands first and routes the clients it finds.
2. It runs `superbot-helper install --register --origin=https://superbot.gg`, which lands the Helper and registers it to start at login.
3. Restart the client and ask it what superbot tools it has. It should list one, `superbot`.

Routing through the Helper is one method. A client can also connect straight to the [MCP server](https://superbot.gg/docs#tool), one at a time, and each has its own recipe: [Claude Code](https://superbot.gg/install/claude.md), [Cursor](https://superbot.gg/install/cursor.md), [VS Code](https://superbot.gg/install/vscode.md), [Codex](https://superbot.gg/install/codex.md), [Gemini CLI](https://superbot.gg/install/gemini.md) and [Claude Desktop](https://superbot.gg/install/claude-desktop.md). The full roster is on the [clients page](https://superbot.gg/clients).

A client with no recipe still connects: point it at the OpenAI or Anthropic dialect base URL for this origin and give it a caller key. The key starts with `sbc_`, and each key carries its own bucket of `1200` requests a minute.

#### Try it

One client with no recipe: set the base URL and key for the dialect it speaks.

**openai dialect**

```sh
export OPENAI_BASE_URL=https://superbot.gg/v1
export OPENAI_API_KEY=sbc_...
# model: superbot
```

**anthropic dialect**

```sh
export ANTHROPIC_BASE_URL=https://superbot.gg
export ANTHROPIC_API_KEY=sbc_...
# model: superbot
```

The agent models a key can dial: `superbot, superbot-omni, superbot-fast`.

[Full client roster](https://superbot.gg/clients) [Mint a caller key](https://superbot.gg/account/api)

### Super mode and swarms

One message to a team of agents across the subscriptions you have connected. A manager splits the work, workers run on your own vendors, and each one reports its cost.

#### How to use it

- Desktop: turn on the Super chip in the composer.
- Terminal: in a `superbot` chat session, type `/super on`.

Over HTTP the same split is two routes. `POST /v1/swarm/route` classifies the intent and returns a plan, with nothing run yet. `POST /v1/swarm/runs` starts the run and streams its events, and the `GET` counterparts poll the run, its usage and its event stream. When the agents in a run message each other, those notes ride the same stream as `a2a` events.

An agent can attach up to four screenshots or images of its progress to a note (PNG, JPEG, WebP or GIF, taken from your own files). They appear beside the note in the activity feed, so you can watch the work take shape.

Every agent also tells you what it is doing while it works. The manager and each worker keep a short plan: an objective and a task list of up to 12 steps, with the current step marked. You also get a one- or two-sentence update at each milestone. Two agent tools carry this: `update_plan` (`{objective?, steps: [{text, status: pending|active|done|skipped}]}`, at most one active step, replacing the agent's plan each time) and `post_update` (`{text, images?}`, at most one every 10 seconds per agent). A plan rides the event stream as an `agent_plan` event (`{type:'agent_plan', agentId, objective?, steps, at}`), and only the latest plan per agent is kept. The run snapshot carries every current plan in `agent_plans`, so a client that joins late still sees them. An update is an `a2a` event with `kind: 'progress'` and `to: 'user'`, and it goes to you, not to the other agents. An agent that has not posted a plan yet shows its objective only (the subtask title, or your request for the manager) with an empty step list.

#### Try it

| Route                            | What it does                                                        |
| -------------------------------- | ------------------------------------------------------------------- |
| POST /v1/swarm/route             | Plans which connected vendors would take the request. Runs nothing. |
| POST /v1/swarm/runs              | Starts a multi-agent run split across those vendors.                |
| GET /v1/swarm/runs/:id           | Polls the run's state.                                              |
| GET /v1/swarm/runs/:id/usage     | Prices each agent's tokens against the run's baseline model.        |
| GET /v1/swarm/runs/:id/events    | Replays and streams the run's events.                               |
| POST /v1/swarm/runs/:id/messages | Sends a note to one agent of a live run.                            |

[API reference](https://superbot.gg/api) [Connect a client](https://superbot.gg/clients)

### Routines

A routine is a standing instruction superbot runs on a schedule, so a task you describe once keeps happening without a reminder.

#### How to use it

1. Describe it in your own words in any connected client, for example: "every weekday at 07:00, summarise my inbox and anything I have not replied to".
2. The model stores it as a routine with a schedule, a time zone and a delivery channel: a text message or a push to your phone.
3. Each time it fires, the standing prompt runs and the result is delivered on that channel.
4. Say "list my routines" to see what is scheduled, or name one and say "pause it", "resume it", "change it" or "delete it". A paused routine keeps its prompt and its schedule, so resuming is one word.

A routine runs on superbot's side on its own clock, so it does not need your machine awake. If a run cannot be delivered, it tells you once on the routine's own channel, naming the reason and the next run. Two missed deliveries in a row pause the routine instead of retrying into silence.

#### Try it

Ask for the routine in plain language and read back the confirmation, which names the cadence, the first run, the zone and the channel. Then ask for the list to confirm it was stored.

What a transcript cannot show you: the schedule belongs to the account, so a pause in one client pauses it everywhere. There is no separate screen to visit if you would rather say it.

[Connect a client](https://superbot.gg/clients) [API reference](https://superbot.gg/api)

### Context and imported chats

The context optimizer trims every relayed turn before it reaches the model, and the account keeps a memory of what you told it, so a long session stops paying to resend stale work and a new session starts from what matters.

#### How to use it

There is nothing to switch on. Every turn that goes out through the relay is trimmed past a payback floor and never past a live cache read, so stale tool output stops costing resends while a warm prompt cache stays warm. `GET /v1/context/:session` reads back what a session used and what it saved, from measured usage rather than an estimate.

Prior chats import so a new session starts with history. The Helper pushes your vendor and harness conversations into the account's imported-chat store, and the same frozen tool can search, fetch and summarise them when a turn needs the background. A remembered preference is written from your own words, and it survives across a week and across devices.

#### Try it

Tell a client a preference once. A week later, in a different session, it still applies. If a later message disagrees, the older record is dated and superseded rather than held alongside the new one, and retrieval can say what it is now and what it was before.

Imported chats are the user's own conversations, held in the account's store and reached through the same frozen tool. The optimizer never trims past a live cache read, so the cache it depends on is never broken to save a resend.

[API reference](https://superbot.gg/api) [Account](https://superbot.gg/account)

### MCP server and the superbot tool

The MCP server is one of the ways an agent reaches superbot. It serves exactly one frozen tool, also named `superbot`, at `https://superbot.gg/mcp`. Give it a plain-text intent and it routes the work to an adapter, the backend that actually does it.

#### How to use it

The tool list never mutates, so a client that connected once keeps working as capabilities grow underneath it. A capability the tool does not have becomes a backend adapter rather than a second tool.

1. Paste a prompt into any client that has the server connected. The client calls `superbot` with your words as the intent.
2. The gateway matches that intent to an adapter. A catalog lookup runs through `search_tools`, an inspection of one adapter runs through `get_tool_details`, and execution runs through `omni`. Those are input modes of the one tool, not separate tools.
3. A fast task comes back as a finished result. A long one comes back with a `request_id` to poll until the result lands.
4. If nothing can serve the intent yet, the miss is logged and grows into an adapter, so the next ask of that shape is answered.

The gateway serves the same tool over the hosted endpoint and through your own Helper. A miss is data, not an error: it is what the next adapter is built from.

The Helper connects the clients it finds for you. To connect one client straight to the server instead, paste this into a coding agent, which fetches `https://superbot.gg/llms.txt` and follows its own client's recipe:

`install the superbot MCP server globally: https://superbot.gg/mcp`

Or add it to Claude Code by hand, for every project:

`claude mcp add --transport http superbot https://superbot.gg/mcp -s user`

#### Try it

In a connected client, paste a prompt in your own words. The client turns it into a tool call against `https://superbot.gg/mcp`; the same call by hand looks like this:

`curl -sS https://superbot.gg/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":"call","method":"tools/call","params":{"name":"superbot","arguments":{"intent":"summarise my unread email"}}}'`

[Connect a client](https://superbot.gg/clients) [API reference](https://superbot.gg/api)

### Your MCP servers

superbot installs, restarts and checks the MCP servers your agents use, so a tool you need is one ask away and a broken one is found before a chat trips on it.

#### What it needs

The Helper, running on your machine. Every server action goes through it; without it the list cannot load.

#### How to use it

1. Ask for the capability in plain words, for example "add a Linear tool". The agent searches the official MCP registry, the Docker MCP catalog, Smithery, npm and GitHub, then offers to install the best match.
2. Installing always asks you first. The Helper starts the server, checks it answers and lists its tools, and installs a missing Node or uv runtime when the server needs one.
3. In the desktop app, open Settings, then **Tools & MCP**, to see every server and whether it works. **Add a tool** adds one by hand, by **HTTP URL** or **Command**.

A server that goes down is restarted once on its own, and shows **Restarting** while it comes back. A row that needs you carries one action: **Sign in**, **Start**, **Check now**, **Turn on** or **Approve change**. **Fix all** and **Retry all** work through the list. Open a server to read its **Last error**, **Config**, **Tools** and **Logs**, or to **Turn off**, **Edit** or **Remove** it.

Each tool's name, description and schema are pinned at install. If a server later changes a tool, its tools are held back until you press **Approve change**; an agent can ask you, but never approves a change itself.

From a terminal, `superbot mcp list` shows each server's state and tool count, `superbot mcp set <id>` adds or edits one, and `superbot mcp remove <id>` removes it.

#### Try it

Ask your agent to "install an MCP server for GitHub", allow the install, then open **Tools & MCP** and find it listed with its tools.

[MCP on the features page](https://superbot.gg/features#mcp) [Get the desktop app](https://superbot.gg/download)

### Built-in tools

Every agent comes with the same set of tools, so one ask can search, read, browse, draw and build a file without anything pasted by hand. There is nothing to install or switch on.

#### What is there

- Web: `web_search`, `fetch_url` and `fetch_or_scrape`, which moves to a real browser when a page needs JavaScript or blocks plain requests. `scrape_js`, `crawl_site` and `site_map` read whole sites.
- Old copies: `archive_url`, `archive_today` and `cdx_index` read a page from web archives when the live one is gone or refuses.
- Research: `papers_search` (OpenAlex, arXiv, Crossref), `deep_research` for a cited report, and `repo_search` for code.
- Your browser and your screen: the `browser_*` tools, and computer use when you allow it. See [Your browser and your screen](https://superbot.gg/docs#computer).
- Media: `image_gen`, `video_gen` and `audio_gen`, on your own accounts. See [Media](https://superbot.gg/docs#media).
- Files: `document_generate` builds a real workbook, document, deck or PDF, with live formulas in spreadsheets. `document_convert` turns a file into a PDF.

The Activity pane in the desktop app shows the tools a run used.

#### Try it

Ask: "brief me on solid state batteries as a deck". Expect a paper search, a few pages read, and a `.pptx` file you can open.

[Tools on the features page](https://superbot.gg/features#tools)

### Browser sessions and saved logins

Your agent works the sites you are already signed into, without ever being handed a password. The Helper seals each session on your device, and every credential class it can reach reaches every device on your account by default.

#### How to use it

Signing in to a site yourself is usually the whole job: the Helper picks up the signed-in session from the browsers you use. On a Mac it reads Chrome, Brave, Edge, Arc, Vivaldi, Firefox and Safari. To seal one site by hand:

`superbot cookies <domain>`

`--dry-run` shows what it would take, and `--yes` skips the prompt.

Saved logins import from your browsers and from 1Password, Bitwarden, LastPass and KeePass. Live 2FA codes come from 1Password when a site asks for one, and are never stored. Sessions, saved passwords, SSH keys, OAuth and vendor credentials, and MCP binding tokens all reach every device on your account by default; only an explicit decline in Settings withholds a class. Where: [Devices](https://superbot.gg/account) on your account lists the enrolled devices, and each connected vendor account can be unlinked from the vault it sits in.

#### Try it

Ask your agent to open a site you are signed into and read something back from it.

[Account](https://superbot.gg/account)

### Your browser and your screen

Anything you do in a browser, your agent can do too: order food, check an Amazon order, pull data off a site, reply to a friend. It works in the background in a browser you do not see, or in front of you on your own screen when you allow it.

#### The browser

Ask in plain words and name the site. The agent opens it, navigates, clicks, types, fills forms, uploads files and takes screenshots. Pages behind your login open signed in as you, from the sessions in [your own browsers](https://superbot.gg/docs#sessions). The first time it uses one, the app asks **Use your <site> sign-in from this Mac?** with **Allow**, **Not now** and **Always**.

The strip above the desktop **Browser** pane picks where agent pages open:

- **Cloud**: a cloud browser works in the background. It cannot reach addresses on your own computer, such as `localhost`.
- **This Mac**: the app's own browser, in the **Browser** pane, where you can watch it work.
- **Auto**, when set: this Mac or the cloud, per page.

**Use my IP** sends the cloud browser's traffic out through your Mac's connection, so sites see your own address.

#### Computer use

With computer use on, the agent can see your screen and use any app: screenshots, reading what is on screen, clicking, typing, scrolling, switching windows and recording the screen. It tries the background first: it clicks and types into an app without moving your cursor or bringing the app to the front. When an app does not accept that, it drives the screen in the foreground while you watch, and moving the mouse or pressing Escape takes it back. It never types into password fields.

1. Press the computer use toggle in the composer. Each press moves it through **Off**, **Ask** and **Always**. It starts at Off.
2. The first time, **Turn on computer use** lists the macOS permissions. **Accessibility** is required, so it can click and type. **Screen Recording** is recommended, so it can take screenshots. **Open Settings** takes you to each one.
3. On Ask, the agent asks **Turn on computer use: <reason>** before it starts, and you allow it once or always.

Computer use runs through the Helper on macOS and Linux. It is not available on Windows.

#### Try it

Ask: "check my last three Amazon orders and tell me when each one arrives".

[Computer use on the features page](https://superbot.gg/features#computer) [Get the desktop app](https://superbot.gg/download)

### Media on your own accounts

Images, video and audio run on your own accounts, so the spend lands where you already pay. superbot tries your sign-in first, then your own key, then its own.

#### How to use it

Sign in to your ChatGPT plan and image generation needs no key at all. With your own keys, images run on OpenAI, Gemini or Grok, video on Sora, Veo or Grok Imagine, and audio on OpenAI or Gemini. An agent asks for one by describing it in plain words, and the finished file comes back at a link under `/gen/`. Each artifact records which account paid for it.

#### Try it

Ask your agent to make an image from a sentence of description, or to turn a paragraph of text into spoken audio.

[Account](https://superbot.gg/account)

### Calls and texts from your phone

Your agent can call and text people for you, from your own iPhone number. You can also text superbot itself and get the answer back as a text.

#### What it needs

A Mac with the Helper running, an iPhone paired to it, and Messages signed in to your Apple Account on the Mac. Calls and texts go out through your iPhone over Continuity, so there is no telephony account to set up. Texts need a Mac with Messages; Windows and Linux cannot send them.

#### How to use it

1. Open Settings, then **Devices & phone**. Under **Voice & calls**, the chip reads **iPhone ready**, **Needs iPhone setup** or **Needs call setup**.
2. Finish the setup it lists: **Allow Messages** (macOS asks to let superbot control Messages), then turn on Full Disk Access for superbot with **Open Full Disk Access**. Calls add a one-time microphone step.
3. Ask in plain words: "text Sam that I am ten minutes late", or "call the dentist and ask for the first free slot next week".

Every call and every text asks you first, each time. A standing "always allow" never covers a dial. If Phone.app needs it, you tap **Call** once on your Mac. The agent on the line works toward the one objective you gave it, and the answer and the transcript come back into the chat. The same number is called at most once a day.

The person who answers hears your cloned voice when one is on file, or a house voice otherwise. To add yours, **Record my voice** under **Voice & calls**, read for 60 seconds, and tick the consent box. **Open calls…** lists the calls and texts your agent made.

#### Text superbot

Text the superbot number and your message runs as an agent turn; the reply comes back as a text. Linking is by texting: the desktop **SMS** pane shows **Text <number> to link a phone**, and there is no link button. On the phone app, Settings, **Text Superbot** shows **Your number** and the **Turn texting on** switch. A [routine](https://superbot.gg/docs#routines) can deliver its result the same way.

Live voice over the API starts with `POST /v1/voice/session`; the client then upgrades to the live socket.

#### Try it

Ask your agent to call somewhere and come back with the answer to one specific question.

[Calls on the features page](https://superbot.gg/features#calls) [Text superbot](https://superbot.gg/sms)

### Build, edit and preview in the app

What your agent builds, you can open, edit and run without leaving the app. A project runs on your Mac for a preview before anything goes online.

#### What it needs

The desktop app, and a project whose folder is on this Mac.

#### How to use it

- **Preview**, in the project header beside **Publish**, runs the app's whole dev stack on this Mac on a `localhost` port. It installs packages first when it needs to, then opens the running app in the side pane. **Stop** ends it.
- Open a file from the project's file tree or its changes list to edit it in the side panel. **Save** (`⌘S`) writes it, **Format** runs the project's own formatter, and **Diff** and **File** switch the view.
- A page or document the agent makes in a chat has **Open in pane**. In the pane, **Edit** lets you change it in place, and **Done** ends editing. **View code** shows the source, **Download** saves it, and each revision can be restored.

#### Try it

Ask your agent for a small web app in a new project, press **Preview**, then open one of its files, change a line and press **Save**.

[Build on the features page](https://superbot.gg/features#build) [Get the desktop app](https://superbot.gg/download)

### Publish to `<name>.superbot.sh`

Publish checks your app, tests it on your Mac, then puts it online at a free `<name>.superbot.sh` address. It runs on your own Cloudflare account, and you manage it from the project in the app.

#### What it needs

A free Cloudflare account, no card needed. The first time, **Connect Cloudflare** opens a dialog: press **Continue to Cloudflare**, sign up or log in, then pick **Use this account**. The app code runs only in your Cloudflare account. You also keep a backup `<sub>.workers.dev` address there.

#### How to use it

1. Open a project and press **Publish** in its header. The chip beside it reads **Ready**, or the number of fixes the check found.
2. Pick the name, and under **Who can open it?** choose **Anyone** or **Only people I invite**.
3. Press **Put it online**. Later publishes read **Update live app**.

Once it is live, the **Live** tab on the project manages it:

- **Versions**: every publish is kept. **Roll back** returns to an older one; it changes your app's code only.
- **Domains**: rename the free address, or **Add a domain** of your own.
- **Live log**: **Start live log** to watch each visit as it happens, **Pause** to stop.
- **Keys**: the secrets your app reads. **Add a key** stores one; its value is never shown again.
- **Who can open it**: switch between public and invited, and **Invite people** by email.
- **Usage** and **Recent errors**, and **Take it offline** (**Remove app**) to delete it for good.

An agent publishes with `/publish`. Railway is an opt-in lane for long-running servers on your own Railway account, and the price is shown before you connect; the chip reads **Needs server lane** when an app needs it. On the phone, a published project shows **Live at <host>** with a Redeploy button.

#### Try it

Ask your agent to build a one-page recipe list, press **Publish**, name it, and open `<name>.superbot.sh`.

[Publish on the features page](https://superbot.gg/features#publish) [Get the desktop app](https://superbot.gg/download)

### Cloud runs from your phone

Send a task from your phone while your Mac is off. It runs on a cloud copy of the project, and the files it changed sync back into your local folder. The project does not need git.

#### What it needs

**Sync projects across devices** on in Settings, and **Sync across devices** on for the project. The run works on the project's synced copy, so the Helper must have synced it at least once. Without it the phone says **Turn on sync to work in the cloud.**

#### How to use it

1. On the phone, open a chat in the project and press the cloud button, **Run in cloud**, in the thread header. On the desktop, the project's **Run in the cloud** row has **Start a run**.
2. The run clones the synced copy, works in a throwaway cloud container, and pushes its changes back.
3. The next time the Helper syncs, the changed files land in your local folder.

A file edited on both sides keeps both copies. Yours stays as it is, and the cloud's version lands beside it as `<name>.sync-conflict-<date>-<time>-cloud.<ext>`. A conflict copy is never overwritten. The project's own `.git`, branches and remotes are never written; git projects merge the same way.

#### Try it

With sync on, ask from the phone: "add a dark mode to the settings page". Open the folder on your Mac after the run to see the changed files.

[Cloud on the features page](https://superbot.gg/features#cloud) [Get the apps](https://superbot.gg/download)

### The omni engine

omni is superbot's own agent loop: the part that sends a turn to the model, runs the tools it asks for, and repeats until the task is done. It is the default engine.

#### How to use it

There is nothing to switch on. omni speaks the two wire dialects, OpenAI and Anthropic, over plain HTTP with no vendor SDK. So any model behind either one, a house model, one of your subscriptions or one of your [custom endpoints](https://superbot.gg/docs#external-apis), runs with the same tools and the same loop.

On paired runs against claude-agent-sdk with the same model, omni finished more tasks with fewer output tokens. The method and the numbers are on the [benchmarks page](https://superbot.gg/benchmarks).

#### Try it

Give the same task to two models from the picker, one of them from a custom endpoint, and compare the runs in the Activity pane.

[omni on the features page](https://superbot.gg/features#omni) [Benchmarks](https://superbot.gg/benchmarks)

### Teams and policy

One signed policy, applied per harness. A team pools MCP servers, rules and skills under one key that the edge never mints, holds or opens.

#### How to use it

1. `POST /v1/org` creates an org: any signed-in account becomes its owner and gets back an org id.
2. `GET /v1/teams` lists the teams you belong to.
3. `PUT /v1/org/:id/policy` writes the policy, and `GET /v1/org/:id/policy` reads it.
4. The Helper posts `POST /v1/org/:id/receipts`, and an admin reads `GET /v1/org/:id/coverage`.
5. Per-agent grants are `POST`, `GET` and `DELETE /v1/agents/grants`.

Every harness is held at the Helper's relay, which drops a server the policy denies. An invite carries one role, always below the inviter's own. Secrets wait for a key wrapped by a teammate's own Helper.

#### Refusals

- `403 agent_not_granted` the agent holds no live grant.
- `403 model_not_allowed` the model is off the allow list.
- `402 member_monthly_limit` the member is out of credits.
- `402 agent_monthly_limit` the agent is out of credits.
- `403 mcp_denied` the policy denies that MCP server.
- `403 invite_email_mismatch` your account's email is not the one invited.
- `400 team_plaintext_refused` a team secret must already be sealed under the team key.

#### Try it

Create an org, invite a teammate with a role below your own, and read the coverage table once their Helper reports in.

[Teams and enterprise](https://superbot.gg/enterprise)

### Usage and spend

See what you have used and what it cost, across every account the Helper manages.

#### How to use it

Your consumption is on the [usage page](https://superbot.gg/account/usage). For a programmatic read, `GET /v1/spend` returns All AI spend across every vendor account the Helper manages, and per-key spend beside it.

A caller key can carry a daily cap and a monthly cap, both in credits, set when the key is minted at [caller keys](https://superbot.gg/account/api#keys). A key that reaches a cap is refused until the window resets.

#### Try it

Set a daily cap when you mint a key, then watch that key's spend appear on the usage page.

[Usage](https://superbot.gg/account/usage)

### External APIs and custom endpoints

Bring any model endpoint and dial it with your own superbot key, beside the house models. There is no limit on how many you add.

#### How to use it

1. In the desktop app, open Settings, then **Subscriptions & keys**. The **External APIs** block lists your **Endpoints**.
2. Under **Add endpoint**, pick a preset: OpenRouter, DeepSeek, Hugging Face or Perplexity. For anything else pick **Other** (**Any endpoint**) and paste an OpenAI- or Anthropic-compatible base URL.
3. Set **Dialect** to **Auto**, **OpenAI** or **Anthropic**. Auto works it out from the endpoint.
4. Add the endpoint's own key, then press **Add endpoint**. Each endpoint keeps its own key.
5. Its models load from the endpoint's `/models`. **Refresh models** reloads them.

**Auto import** finds API keys already on this Mac (shell rc files, `.env` files and `~/.config`), tests them, and offers each one as an endpoint. You need to be signed in to import.

Every endpoint's models join the model picker. Over the API, dial one as `custom/<endpoint>/<model>`, beside the house ids `superbot, superbot-omni, superbot-fast`. `GET /v1/models` lists everything your key can dial, custom ids included. Caller keys start with the prefix `sbc_` and are minted at [caller keys](https://superbot.gg/account/api#keys).

#### Try it

Add OpenRouter with your OpenRouter key, then call `custom/openrouter/<model>` with your superbot key.

[Endpoints on the features page](https://superbot.gg/features#endpoints) [Caller keys](https://superbot.gg/account/api#keys)

## API

The same agents the app and your AI clients use, over plain HTTP, with a key you mint and can revoke. Every figure on this section is read from the live tables at request time.

### Keys and authentication

Every call carries a caller key. A caller key is a credential you mint on your account, scope to one lane, set a spend cap on, and revoke on its own.

#### What a key is

A caller key starts with `sbc_`. It is shown in full exactly once, when you mint it; after that the account only ever shows its mask. It belongs to your account, not to a machine, and it is what the gateway bills: every request it answers lands in your balance and in that key's own spend.

#### Mint one

1. Open [Caller keys](https://superbot.gg/account/api#keys) on your account.
2. Name it after the thing that will use it. The name is free text and is how you will recognize it later.
3. Pick a lane: `byo` runs on the vendor accounts your Helper has attached and costs no credits, `credits` spends your superbot credit balance, `auto` uses your own account when one is attached and credits otherwise.
4. Pick a mode: `model` dials the model id you send, `agent` runs the full superbot agent, tools included.
5. Optionally set a daily cap, a monthly cap, or a model allow-list, all in credits and all editable later.
6. Copy the key when it is offered. Nothing can show it again.

Revoking is immediate, and a key's own key id is what the account page and the API both address it by. Rotating is mint, cut over, revoke: there is no in-place reveal.

#### How a request authenticates

```sh
curl https://superbot.gg/v1/models \
  -H "Authorization: Bearer sbc_…"
```

`x-api-key` carries the same key and is what some Anthropic-shaped clients expect. A session cookie is the other bearer: it authenticates your own account for the routes that act on it, and it is never the right credential for a third-party client, which needs a key of its own.

Give each client its own key. One key per client is what makes the spend pane readable and a leak one revoke instead of an audit.

#### Third-party clients

Pointing a client that is not one of ours at this API: [the base URL, caller key and model ids for each client](https://superbot.gg/clients) are laid out per client, with the OpenAI and Anthropic base URLs both spelled out.

#### Try it

List every model this key may dial, then send one message. Both are one request each:

**curl**

```sh
curl https://superbot.gg/v1/models \
  -H "Authorization: Bearer sbc_…"
```

**python**

```python
from openai import OpenAI

client = OpenAI(base_url="https://superbot.gg/v1", api_key="sbc_…")
for model in client.models.list():
    print(model.id)
```

[Mint a caller key](https://superbot.gg/account/api#keys) [The rate card](https://superbot.gg/api)

### Models

Two lanes share one model list. The three house ids run superbot's own agent. The vendor ids are the models your own accounts and keys reach.

#### House models

These are the ids a caller may dial to get an agent rather than a raw model: `superbot, superbot-omni, superbot-fast`. `superbot` is the full agent, `superbot-omni` is the agent on the omni engine, `superbot-fast` is the agent on the fast tier, 500k context.

__house model rates__
| Model                     | Input | Output | Cache read | Cache write |
| ------------------------- | ----- | ------ | ---------- | ----------- |
| superbot                  | 200   | 800    | 5          | 200         |
| superbot-fastfree in beta | 100   | 400    | 3          | 100         |

Credits per 1M tokens; one credit is $0.001.

superbot-fast is free in beta.
fair use: 500 credits per 5 hours, 2,000 credits per 7 days.
past that, it bills at the rates above.

superbot-fast was formerly superbot-flash, and that id is still accepted.

#### Vendor models

Models on your own subscriptions and keys are free on superbot.
superbot adds no credits to those calls.
You pay your provider as usual.

These are the models the accounts your Helper has attached reach, and the keys you added.
The rates below apply only when you dial a vendor model on superbot credits, with no account of yours attached.

__vendor model rates on superbot credits__
| Model                      | Input  | Output | Cache read | Cache write |
| -------------------------- | ------ | ------ | ---------- | ----------- |
| claude-fable-5-1           | 10,000 | 50,000 | 250        | n/a         |
| claude-opus-5-5            | 4,000  | 20,000 | 200        | n/a         |
| claude-opus-5              | 5,000  | 25,000 | 500        | n/a         |
| claude-sonnet-5            | 2,000  | 10,000 | 200        | n/a         |
| claude-haiku-4-5           | 1,000  | 5,000  | 100        | n/a         |
| gpt-6-astra                | 10,000 | 50,000 | 1,000      | 12,500      |
| gpt-6-sol                  | 2,000  | 10,000 | 200        | 2,500       |
| gpt-6-luna                 | 100    | 500    | 10         | 125         |
| grok-4.7                   | 2,000  | 6,000  | 500        | n/a         |
| muse-spark-1.3             | 1,250  | 4,250  | 150        | n/a         |
| muse-spark-1.3-contributor | 100    | 200    | 2          | n/a         |
| muse-spark-1.2             | 1,250  | 4,250  | 150        | n/a         |
| muse-spark-1.2-contributor | 100    | 200    | 2          | n/a         |
| muse-spark-1.1             | 1,250  | 4,250  | 150        | n/a         |
| deepseek-flash             | 300    | 1,200  | 6          | n/a         |
| deepseek-v4-pro            | 1,320  | 3,960  | 44         | n/a         |
| deepseek-chat              | 300    | 1,200  | 6          | n/a         |
| deepseek-reasoner          | 300    | 1,200  | 6          | n/a         |
| gemini-3.8-flash           | 750    | 3,750  | 75         | n/a         |
| gemini-flash               | 750    | 3,750  | 75         | n/a         |
| gemini-flash-latest        | 750    | 3,750  | 75         | n/a         |
| gemini-3.1-pro             | 2,000  | 12,000 | 200        | n/a         |

Credits per 1M tokens; one credit is $0.001.

#### Custom upstreams

An endpoint you added under Settings > External APIs joins the same list as `custom/<endpoint>/<model>`. It is routeable by that exact spelling, so `custom/example/llama-3.3-70b` reaches your own upstream with the same key the house ids take. `GET /v1/models` publishes both, which is why it is the one call worth making first: it is the list the gateway will accept, from the gateway itself.

[External APIs](https://superbot.gg/docs#external-apis) [Attach a vendor account](https://superbot.gg/account/api#providers)

### Endpoints

Every public route, grouped by what it does.
Each links to its full reference on [/developers](https://superbot.gg/developers).
They all take the same caller key, bill the same balance and dial the same model ids.

The scope column is what a caller key must hold to call the route. `any key` takes any live key, and `no key` answers without one.

#### Call models

[Full reference](https://superbot.gg/developers/gateway)

__Call models routes__
| Method | Path                                                                                    | What it does                                    | Scope          |
| ------ | --------------------------------------------------------------------------------------- | ----------------------------------------------- | -------------- |
| POST   | [/v1/chat/completions](https://superbot.gg/developers/gateway/createChatCompletion)     | Create a chat completionOpenAI Chat Completions | gateway:invoke |
| POST   | [/v1/responses](https://superbot.gg/developers/gateway/createResponse)                  | Create a responseOpenAI Responses               | gateway:invoke |
| POST   | [/v1/messages](https://superbot.gg/developers/gateway/createMessage)                    | Create a messageAnthropic Messages              | gateway:invoke |
| POST   | [/v1/messages/count_tokens](https://superbot.gg/developers/gateway/countMessageTokens) | Estimate input tokensAnthropic, nothing billed  | any key        |
| GET    | [/v1/models](https://superbot.gg/developers/gateway/listModels)                         | List modelsOpenAI and Anthropic                 | any key        |

#### Manage keys

[Full reference](https://superbot.gg/developers/keys)

__Manage keys routes__
| Method | Path                                                                 | What it does        | Scope      |
| ------ | -------------------------------------------------------------------- | ------------------- | ---------- |
| GET    | [/v1/keys](https://superbot.gg/developers/keys/listKeys)             | List caller keys    | keys:read  |
| POST   | [/v1/keys](https://superbot.gg/developers/keys/createKey)            | Create a caller key | keys:write |
| GET    | [/v1/keys/whoami](https://superbot.gg/developers/keys/getCurrentKey) | Get the calling key | any key    |
| PATCH  | [/v1/keys/{id}](https://superbot.gg/developers/keys/updateKey)       | Update a caller key | keys:write |
| DELETE | [/v1/keys/{id}](https://superbot.gg/developers/keys/revokeKey)       | Revoke a caller key | keys:write |

#### Usage and spend

[Full reference](https://superbot.gg/developers/usage)

__Usage and spend routes__
| Method | Path                                                                          | What it does                   | Scope        |
| ------ | ----------------------------------------------------------------------------- | ------------------------------ | ------------ |
| GET    | [/v1/usage](https://superbot.gg/developers/usage/getUsage)                    | Get usage over a window        | usage:read   |
| GET    | [/v1/usage/requests](https://superbot.gg/developers/usage/listUsageRequests)  | List usage per request         | usage:read   |
| GET    | [/v1/usage/daily](https://superbot.gg/developers/usage/getUsageDaily)         | Get usage per UTC day          | usage:read   |
| GET    | [/v1/usage/breakdown](https://superbot.gg/developers/usage/getUsageBreakdown) | Get usage bucketed and grouped | usage:read   |
| GET    | [/v1/usage/export](https://superbot.gg/developers/usage/exportUsage)          | Export usage rows              | usage:read   |
| GET    | [/v1/credits](https://superbot.gg/developers/usage/getCredits)                | Get the credit balance         | billing:read |
| GET    | [/v1/spend](https://superbot.gg/developers/usage/getSpend)                    | Get AI spend across apps       | usage:read   |
| GET    | [/v1/usage/report](https://superbot.gg/developers/usage/getUsageReport)       | Get a usage report             | usage:read   |

#### Custom endpoints

[Full reference](https://superbot.gg/developers/endpoints)

__Custom endpoints routes__
| Method | Path                                                                                             | What it does                     | Scope           |
| ------ | ------------------------------------------------------------------------------------------------ | -------------------------------- | --------------- |
| GET    | [/v1/upstreams](https://superbot.gg/developers/endpoints/listUpstreams)                          | List custom endpoints            | endpoints:read  |
| POST   | [/v1/upstreams](https://superbot.gg/developers/endpoints/createUpstream)                         | Add a custom endpoint            | endpoints:write |
| PATCH  | [/v1/upstreams/{slug}](https://superbot.gg/developers/endpoints/updateUpstream)                  | Update a custom endpoint         | endpoints:write |
| DELETE | [/v1/upstreams/{slug}](https://superbot.gg/developers/endpoints/deleteUpstream)                  | Remove a custom endpoint         | endpoints:write |
| POST   | [/v1/upstreams/{slug}/probe](https://superbot.gg/developers/endpoints/probeUpstream)             | Re-probe a custom endpoint       | endpoints:write |
| GET    | [/v1/aliases](https://superbot.gg/developers/endpoints/listAliases)                              | List @mention aliases            | endpoints:read  |
| PUT    | [/v1/aliases/{token}](https://superbot.gg/developers/endpoints/setAlias)                         | Set an @mention alias            | endpoints:write |
| DELETE | [/v1/aliases/{token}](https://superbot.gg/developers/endpoints/deleteAlias)                      | Delete an @mention alias         | endpoints:write |
| GET    | [/docs/services/{service_id}.json](https://superbot.gg/developers/endpoints/getServiceDocument) | Get a service’s OpenAPI document | no key          |

#### Teams

[Full reference](https://superbot.gg/developers/teams)

__Teams routes__
| Method | Path                                                                                                | What it does              | Scope       |
| ------ | --------------------------------------------------------------------------------------------------- | ------------------------- | ----------- |
| GET    | [/v1/teams](https://superbot.gg/developers/teams/listTeams)                                         | List teams                | teams:read  |
| POST   | [/v1/teams](https://superbot.gg/developers/teams/createTeam)                                        | Create a team             | teams:write |
| GET    | [/v1/teams/{team_id}](https://superbot.gg/developers/teams/getTeam)                                | Get a team                | teams:read  |
| PATCH  | [/v1/teams/{team_id}](https://superbot.gg/developers/teams/updateTeam)                             | Update a team             | teams:write |
| DELETE | [/v1/teams/{team_id}](https://superbot.gg/developers/teams/deleteTeam)                             | Delete a team             | teams:write |
| GET    | [/v1/teams/{team_id}/members](https://superbot.gg/developers/teams/listTeamMembers)                | List team members         | teams:read  |
| PATCH  | [/v1/teams/{team_id}/members/{user_id}](https://superbot.gg/developers/teams/updateTeamMember)    | Change a member’s role    | teams:write |
| DELETE | [/v1/teams/{team_id}/members/{user_id}](https://superbot.gg/developers/teams/removeTeamMember)    | Remove a team member      | teams:write |
| GET    | [/v1/teams/{team_id}/invites](https://superbot.gg/developers/teams/listTeamInvites)                | List pending team invites | teams:read  |
| POST   | [/v1/teams/{team_id}/invites](https://superbot.gg/developers/teams/createTeamInvite)               | Invite someone to a team  | teams:write |
| DELETE | [/v1/teams/{team_id}/invites/{code}](https://superbot.gg/developers/teams/revokeTeamInvite)        | Revoke a team invite      | teams:write |
| POST   | [/v1/teams/{team_id}/invites/{code}/resend](https://superbot.gg/developers/teams/resendTeamInvite) | Resend a team invite      | teams:write |
| POST   | [/v1/team_invites/{code}/accept](https://superbot.gg/developers/teams/acceptTeamInvite)            | Accept a team invite      | teams:write |

#### Devices

[Full reference](https://superbot.gg/developers/devices)

__Devices routes__
| Method | Path                                                                            | What it does    | Scope         |
| ------ | ------------------------------------------------------------------------------- | --------------- | ------------- |
| GET    | [/v1/devices](https://superbot.gg/developers/devices/listDevices)               | List devices    | devices:read  |
| GET    | [/v1/devices/{device_id}](https://superbot.gg/developers/devices/getDevice)    | Get a device    | devices:read  |
| PATCH  | [/v1/devices/{device_id}](https://superbot.gg/developers/devices/updateDevice) | Rename a device | devices:write |
| DELETE | [/v1/devices/{device_id}](https://superbot.gg/developers/devices/deleteDevice) | Unlink a device | devices:write |

[Full API reference](https://superbot.gg/developers) [OpenAPI 3.1 spec](https://superbot.gg/docs/openapi.json)

#### Send a message

One request, three spellings. The body is the dialect's own, so an existing client only needs its base URL and key pointed here.

**curl**

```sh
curl https://superbot.gg/v1/chat/completions \
  -H "Authorization: Bearer sbc_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "superbot",
    "messages": [{"role": "user", "content": "Summarise this thread and tell me what I owe a reply to."}]
  }'
```

**OpenAI SDK**

```python
from openai import OpenAI

client = OpenAI(base_url="https://superbot.gg/v1", api_key="sbc_…")
stream = client.chat.completions.create(
    model="superbot",
    messages=[{"role": "user", "content": "Summarise this thread."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

**Anthropic SDK**

```python
from anthropic import Anthropic

client = Anthropic(base_url="https://superbot.gg", api_key="sbc_…")
with client.messages.stream(
    model="superbot",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise this thread."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="")
```

#### Streaming

Send `"stream": true` to `/v1/chat/completions`, `/v1/responses` or `/v1/messages` and the reply is server-sent events in that dialect's own shape.

- Chat Completions sends `data: {"choices":[…]}` frames and ends with `data: [DONE]`.
- Responses sends its typed events, `response.output_text.delta` and the rest, and ends with `response.completed`.
- Messages sends Anthropic's event names, from `message_start` to `message_stop`.

Nothing else changes: usage and billing land at the end of the stream, and an aborted stream is billed for what it produced. The three are POST-only, so `GET /v1/chat/completions` is not a route.

#### Read a session back

The context optimizer trims every relayed turn before it reaches a model. What a session used and saved is readable on its own route:

```sh
curl https://superbot.gg/v1/context/<session_id> \
  -H "Authorization: Bearer sbc_…"
```

[Context and imported chats](https://superbot.gg/docs#context) [Full request and response shapes](https://superbot.gg/developers/gateway)

### Limits and errors

One bucket per key, and one refusal per thing that can go wrong. Every refusal names its own code, so a client can branch on the code instead of the sentence.

#### Rate limits

A caller key gets 1200 requests a minute. The bucket is per key, so one noisy client cannot spend another's headroom, and a session cookie is not in that bucket at all. Over it, the gateway answers `429` and the call is refused before any vendor is dialed, which means it costs nothing.

#### Refusals

| Status | Code                  | What it means                                                            |
| ------ | --------------------- | ------------------------------------------------------------------------ |
| 401    | invalid_api_key     | the key is missing, misspelled or revoked                                |
| 402    | insufficient_balance | the balance, the plan allowance and the packs are all spent (body below) |
| 403    | agent_not_granted   | an agent id with no live grant on this account                           |
| 403    | model_not_allowed   | the key's own allow-list does not name that model                        |
| 403    | mcp_denied           | team policy denies that MCP server, so no connect is started             |
| 404    | model_not_found     | no vendor and no stored upstream claims that model id                    |
| 429    | rate_limit_error    | over this key's per-minute bucket; retry after the window                |
| 5xx    | api_error            | the upstream failed; the retry is the caller's to make                   |

#### The 402 body

A request the wallet cannot cover answers HTTP 402. The body keeps the three fields existing clients read (error, topup_url, balance_tokens) and adds the subscription context, with the account's own live figures in it:

```json
{
  "error": "insufficient_balance",
  "topup_url": "https://superbot.gg/topup?t=…",
  "balance_tokens": 0,
  "plan": "sub",
  "reason": "allowance_exhausted",
  "renews_at": "2026-10-01T00:00:00.000Z",
  "plan_name": "superbot plus",
  "plan_price_usd_month": 20,
  "plan_allowance_tokens": 20000,
  "overage_rate_usd_per_1k": 1,
  "auto_recharge": {
    "enabled": true,
    "threshold_mtok": 0,
    "amount_usd": 20,
    "monthly_cap_usd": 100,
    "spent_this_month_usd": 20
  },
  "subscribe_url": "https://superbot.gg/topup?t=…",
  "manage_url": "https://superbot.gg/account#plan",
  "byo_url": "https://superbot.gg/account#key",
  "recharge_url": "https://superbot.gg/recharge?t=…",
  "grants": [],
  "ledger_balance_tokens": 0,
  "plan_tier": "plus"
}
```

`reason` tells you which refusal this is: `no_plan`, `topup_only`, `allowance_exhausted`, `auto_recharge_off`, `recharge_cap_reached`, `recharge_failed` or `weekly_cap_reached`. Amounts are credits; the fields named `_tokens` keep their older names and carry credits now. `overage_rate_usd_per_1k` appears only when a rate is configured, and `GET /v1/credits` answers the same shape without the two fields that only a refusal carries.

Operators reprice without a deploy: `SUPERBOT_PLANS` overrides the plan table as a JSON array of `{id, name, price_usd_month, allowance_tokens, overage_usd_per_1k_tokens}`, and `SUPERBOT_STRIPE_PRICE_5`, `_20` and `_100` reprice the $5/$20/$100 packs. [The API page](https://superbot.gg/api) renders the same tables this page does, so a repricing moves both.

A 402 is a wallet answer, not a broken request. The body carries `topup_url` so a client can send the reader straight to the recharge it needs.

[Credits and plans](https://superbot.gg/docs#billing) [Your usage](https://superbot.gg/account/usage)

## Account and billing

### Credits

Every balance, allowance and cap is a whole number of credits, and one credit is always the same fraction of a dollar.

superbot bills in credits: one credit is $0.001. The house models are priced per token below the vendor's own list (on superbot: output counted at 4x, cache reads at 0.025x and cache writes at 1x). [The API page](https://superbot.gg/api) holds the full rate card, and [Models](https://superbot.gg/docs#api-models) above shows the same rows as the gateway serves them.

superbot-fast is free in beta.
fair use: 500 credits per 5 hours, 2,000 credits per 7 days.
past that, it bills at its rate on the rate card.

Models on your own subscriptions and keys are free on superbot.
superbot adds no credits to those calls.
You pay your provider as usual.

A vendor model you dial on superbot credits, with no account of yours attached, is charged at its own list price.

What spends first when you hold several pots: the monthly allowance that comes with a plan, then pack credits, then the auto-recharge you turned on. The monthly allowance is spent after the beta pot and before pack credits, expires at renewal and does not roll over; pack credits never expire.

#### Read your balance

```sh
curl https://superbot.gg/v1/credits \
  -H "Authorization: Bearer sbc_…"
```

### Plans and packs

Four tiers, and a pack you can buy with or without one.

**free** costs nothing and carries a monthly 10,000-credit beta pot, refilled on the 1st (UTC). **superbot plus** is $20 a month with 20,000 credits included, **pro** is $100 a month with 100,000, and **max** is $200 a month with 200,000.

Packs stay available below any plan, reached from [the billing page](https://superbot.gg/account/billing) and from the link in every 402: 5,000 credits for $5, 20,000 for $20, 100,000 for $100. A pack is one purchase, not a subscription, and its credits stay in the balance until they are spent.

#### Auto-recharge

**auto-recharge** buys another pack automatically once the balance runs out: off until you turn it on, then $20 per charge, capped at $100 per calendar month, both editable on [the billing page](https://superbot.gg/account/billing), whose form posts to /account/recharge. The same page links Stripe's billing portal, where the subscription can be cancelled and the card changed. Failed charges count toward the monthly cap, and cancelling keeps every pack credit already banked. While a top-up is in flight the internal balance can dip slightly negative; what the apps show never goes below zero.

[Buy credits or change plan](https://superbot.gg/account/billing) [Usage and spend](https://superbot.gg/docs#usage)

### Which credits are spent first

An account on a subscription spends its monthly allowance first, then any pack credits it holds, then whatever auto-recharge buys. A failed or skipped recharge never cancels a plan: the subscription stays, the allowance refills at renewal, and a balance that reads empty is a balance, not a lapsed account.

## Help

### Troubleshooting

The four things that actually go wrong on a fresh install, and what each one means.

#### A client does not show superbot

Restart it. The installer writes each client's config while that client is closed, so a running window keeps the config it read at launch. If it still does not appear, the recipe for that client in [Your AI clients](https://superbot.gg/docs#clients) lists the exact file it writes and how to check it.

#### superbot: command not found after install

Re-run the install line, or paste the line it printed at the end so this shell finds it: `export PATH="$HOME/.superbot/bin:$PATH"` on sh, bash and zsh, `set -gx PATH $HOME/.superbot/bin $PATH` on fish, and `$env:Path = "$HOME\.superbot\bin;$env:Path"` on PowerShell. A close of `superbot was not placed on PATH: <file>` means remove that file and re-run. A new terminal does the same thing as the export.

#### Nothing here needs node

The install line never touches node, npm or an rc file. The Helper ships as one signed binary, from Homebrew when it is on your PATH, else a direct download verified against a checksum before it runs. An install that fails partway is safe to just re-run, or add `--force`.

#### A pairing prompt appears

Running a tool may ask you to pair once. That is the step that ties this device to your account, and it is what lets the Helper hold your vendor credentials on this machine instead of on the edge. Pairing again on a second machine adds a device; it does not replace the first.

#### The key I pasted is refused

A 401 means the key is missing, misread or revoked. Mint a new one at [Caller keys](https://superbot.gg/account/api#keys) and paste the whole string: it starts with `sbc_` and is shown in full exactly once, at mint. A 403 with `model_not_allowed` is the other case: the key is fine and its own model allow-list does not name what you asked for.

### Uninstall

One command, and it asks before it deletes anything.

`superbot uninstall` deletes the Helper, the desktop app and its data, superbot's entries in your AI clients (their other entries and settings stay), and your local accounts, chats and keys, so you sign in again after a reinstall. `superbot uninstall --dry-run` lists what would go and deletes nothing, and a script with no terminal has to pass `--yes`.

Routed a single client by hand instead? Remove the entry the way it was added: `claude mcp remove superbot` for Claude Code, or delete the `superbot` entry from that client's config file. Nothing else was installed.

[Per-client setup](https://superbot.gg/docs#clients) [Reinstall the desktop app](https://superbot.gg/download)

### More ways to read this

The same documentation, in the shapes other tools want.

- [llms.txt](https://superbot.gg/llms.txt): every install recipe and the MCP endpoint, as an agent reads it.
- [docs.md](https://superbot.gg/docs.md): this page as markdown, without the live account strip.
- [clients](https://superbot.gg/clients): the per-client setup pages, one per editor, CLI and SDK.
- [api](https://superbot.gg/api): the full rate card and the wire shapes.
- [enterprise](https://superbot.gg/enterprise): teams, policy and coverage.
- [request a harness](https://superbot.gg/request-harness): a client that is not on the list yet.