--- title: "superbot docs: the app, the Helper and its CLI" canonical_url: "https://superbot.gg/docs" summary: "how to install the superbot app, the Helper and its CLI, and what each feature does." --- > Markdown of https://superbot.gg/docs. Site index: /llms.txt. by 588 px, CLS 0.553) --> Docs contents Filter this page [superbot.gg](https://superbot.gg/) / docs # Docs superbot is your own AI agent: one model that makes pictures, video, songs, 3D and apps, on desktop and phone. ## How do you work? [ I want the app ](https://superbot.gg/docs#mode-app) [ I keep my own app ](https://superbot.gg/docs#mode-harness) [ I only call API ](https://superbot.gg/docs#mode-api) [ I only want MCP ](https://superbot.gg/docs#mode-mcp) ### I want the app Make pictures, video, songs and apps in the desktop app. [Download superbot](https://superbot.gg/download) [Desktop and phone apps](https://superbot.gg/docs#apps) ### I keep my own app Claude Code keeps working. **macOS and Linux** `curl -fsSL https://superbot.gg/bootstrap.sh | sh -s -- --relay-app` Without the app, use `--no-app` **Windows** `& ([scriptblock]::Create((irm https://superbot.gg/bootstrap.ps1))) -RelayApp` Without the app, use `-NoApp` [Download superbot relay](https://superbot.gg/download#relay) The relay runs `claude -p` on Omni. Tidy is on by default and sends fewer rules. [About superbot relay](https://superbot.gg/docs#relay-app) [Local relay API](https://superbot.gg/docs#relay-api) ### I only call API Any OpenAI or Anthropic client works. `curl https://api.superbot.gg/v1/models -H "Authorization: Bearer sbc_…"` Remote Omni`claude --model superbot-omni` [Keys and authentication](https://superbot.gg/docs#api-auth) [Endpoints](https://superbot.gg/docs#api-endpoints) [Routing by key](https://superbot.gg/docs#api-routing) ### I only want MCP Any MCP client works. Paste this into your agent. `install the superbot MCP server globally: https://superbot.gg/mcp install the superbot skill globally: https://superbot.gg/skills/superbot/SKILL.md Tell me if I need to sign in.` Then type `/superbot` in your agent. In Codex, type `$superbot`. No account? Your agent follows [/auth.md](https://superbot.gg/auth.md). Or add the server URL yourself. `https://superbot.gg/mcp` No browser? Signed in, [copy a key](https://superbot.gg/download#mcp). [Per-client recipes](https://superbot.gg/docs#clients) [MCP endpoints](https://superbot.gg/docs#mcp-endpoints) ### Install The default route installs the Helper, opens a browser to sign you in and finishes with the desktop app. It routes no AI app through superbot: you switch an app on under Your apps in superbot relay, or add `--wire` (`-Wire` on Windows) to route the AI clients it finds at install time. Add `--no-app` (`-NoApp` on Windows) to install the Helper and CLI alone, and run the installer again to update. The second route is superbot relay: use your own harness. It installs the Helper and CLI plus the standalone superbot relay app in place of the desktop app, with the same sign-in. Add `--relay-app` (`-RelayApp` on Windows). Its card on [Download superbot](https://superbot.gg/download#relay) appears once the app has a release, and a computer with no release for it gets the Helper and CLI, with a line saying so. Related: [MCP server and its tool](https://superbot.gg/docs#tool) ### Verify Restart an AI client you routed through superbot (in superbot relay, or with `--wire`) and ask it what superbot tools it has. It lists one tool, `superbot`. Checking the server from this browser… `what superbot tools do you have?` ### Your connection MCP endpoint `https://superbot.gg/mcp` API base `https://api.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/account) ## For agents ### Which surface to use Match the job to a row. The Auth column is what you send. | Job | Surface | Auth | | ------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Call a model with an OpenAI or Anthropic SDK | https://api.superbot.gg/v1 (hosted base) | caller key sbc\_…, or a saved provider key. [Routing by key](https://superbot.gg/docs#api-routing) | | Call a model on this computer's own subscriptions | http://127.0.0.1:18787/v1 (local base URL) | relay key sk-superbot-…, caller key sbc\_…, or account key sbk\_…. [Local relay API](https://superbot.gg/docs#relay-api) | | Hand a whole task to superbot in plain words | https://superbot.gg/mcp, tool superbot. Or model superbot on https://api.superbot.gg/v1 | MCP: OAuth sign-in or the install token. Model: caller key sbc\_…. [MCP endpoints](https://superbot.gg/docs#mcp-endpoints) | | Call the user's own MCP tools from elsewhere | POST https://api.superbot.gg/v1/mcp | caller key with the mcp:invoke scope, or account key sbk\_…. [MCP endpoints](https://superbot.gg/docs#mcp-endpoints) | | Use agent tools inside a session the Helper runs | http://127.0.0.1:18787/mcp | relay key, or account key sbk\_…. [Local relay API](https://superbot.gg/docs#relay-api) | | Read these docs as markdown or OpenAPI | https://superbot.gg/docs.md, https://superbot.gg/docs/openapi.json | none. [Discovery and access](https://superbot.gg/docs#discovery) | ### MCP endpoints Three endpoints, one per job. Each takes its own auth. | Endpoint | Serves | Auth | | ----------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | https://superbot.gg/mcp | one tool, superbot | OAuth sign-in, or the install token | | POST https://api.superbot.gg/v1/mcp | the user's own MCP tools, each named \_\_ | caller key with mcp:invoke, or account key sbk\_… | | http://127.0.0.1:18787/mcp | the agent tools on this computer | relay key, or account key sbk\_…; a caller key sbc\_… answers 403 caller_key_forbidden | #### The superbot tool | Argument | Mode | | ------------------------- | --------------------------------------------------------------------------------------------- | | use_case, without intent | search: returns session_id, tools (each with slug and one_liner), connection_info and miss | | slug, alone | one tool's details | | intent | run the task | | session_id | continue an earlier search or run | The skills CLI installs the superbot skill: `npx skills add https://superbot.gg`. Once it is installed, a user can say `use superbot`, and the agent calls `superbot` with the rest of the request. #### Link install Mint an install code with `POST https://superbot.gg/mcp/install`. Name the client with `client=` in the query, a JSON body or a form body. Values: `claude-code`, `codex`, `gemini-cli`, `cursor`, `vscode`, `cline`, `zed`, `windsurf`, `other`. An unknown value is `other`. ```bash curl -X POST 'https://superbot.gg/mcp/install?client=claude-code' ``` | Reply field | Meaning | | ------------ | ------------------------------------------------------------------- | | token | the install's bearer token | | mcp_url | the MCP endpoint to connect | | user_code | the code the owner approves | | link_url | https://superbot.gg/link/, where the owner approves it | | expires_in | seconds the code lives: 900 | | config | the client's config | | add, replace | claude-code only: the claude mcp add and claude mcp remove commands | | add | gemini-cli only: the gemini mcp add command | | config_toml | codex only: the TOML block | Over a rate limit, the call answers `429 rate_limited` with `retry_after`, `limit` and a `Retry-After` header. Too many pending installs answer `503 temporarily_unavailable` with `retry_after`. #### Your own MCP tools - Methods: `initialize`, `ping`, `tools/list` and `tools/call`, as JSON-RPC 2.0. - Auth: a caller key with `mcp:invoke`. A key without the scope answers `403 insufficient_scope`. An account key `sbk_…` is accepted. A session or device token answers `403 caller_key_required`. No key answers `401 unauthorized` with a `WWW-Authenticate: Bearer` header. - Names: `__`. Servers named `hub` or `superbot` are never served. - Limits: 120 `tools/call` a minute per key, and 8 running at once per user. Over either limit: `429 rate_limited` with `retry_after` and a `Retry-After` header. - Refusal codes for a `tools/call`: `remote_mcp_off` (the switch is off), `device_offline` (no paired device is online) and `unknown_tool`. The call answers as an error result (`isError: true`). - Switch: relay app, MCP page, "Your tools, remotely", "Allow remote MCP tools". See [Your own MCP tools, remotely](https://superbot.gg/docs#remote-mcp). ```bash curl -X POST https://api.superbot.gg/v1/mcp \ -H "Authorization: Bearer sbc_…" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` #### Agent tools on this computer Served at `http://127.0.0.1:18787/mcp` with a relay key or account key `sbk_…`. A caller key `sbc_…` answers `403 caller_key_forbidden`. Mounted in the agent sessions the Helper runs: its own agent, the Claude Agent SDK, Codex, and Cursor and Claude over ACP. | Family | Tools | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Files | hub\__fs\_\* | | Rules and skills | hub\__rules\_\*, hub\__skills\_\*, hub\__skill | | Memory and ledger | hub\__memory\_\*, hub\__todo_read, hub\__todo_write, hub\__pin_context | | Delegation and peers | hub\__delegate\*, hub\__peer\_\* | | Credentials | hub\__creds_list, hub\__creds_put | | MCP servers | hub\__mcp_search, hub\__mcp_install, hub\__mcp_set_enabled, hub\__mcp_remove, hub\__mcp_approve_change, hub\__mcp_refresh | | Projects and apps | hub\__projects\_\*, hub\__clients_list, hub\__clients_wire, hub\__clients_unwire | | Phone | hub\__phone\_\*, hub\__sms_send | | Settings | hub\__settings_set | | Acquire | hub\__acquire | | Publish and deploy | publish_check, publish_prepare, deploy_status, deploy_versions, deploy_secrets_list, deploy_run | ### Local relay API The Helper serves the local base URL from this computer. - Base URL: `http://127.0.0.1:18787/v1`. Default port: 18787. Read the port on the relay app's Overview page, in the Endpoint card with Local picked, on the Base URL row. - Routes: `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/chat/completions`, `POST /v1/responses`. - Sign-ins served: Claude, ChatGPT, Gemini, Grok, Muse Code, Kimi Code and GLM Coding Plan. Each answers in either API: a Claude model answers `POST /v1/chat/completions`, and a GPT model answers `POST /v1/messages`. - No key: `GET /v1/models`, `GET /health`. - Key required: `GET /v1/keys/whoami`, every other `/v1/*` route, and `/mcp`. - Accepted keys: - relay key `sk-superbot-…`, sent as `Authorization: Bearer` or `x-api-key`; - caller key `sbc_…` and account key `sbk_…`; - saved Anthropic or OpenAI provider key, on its own vendor's routes only. Other routes answer `403 provider_key_wrong_vendor`. - Relay switched off (the **Relay** switch in the superbot relay card on the relay app's Overview page): every `/v1` route answers `503 relay_off` to every key; `/health` and `/mcp` keep answering. - Relay key mint: the Helper mints a relay key on its first run and prints it. `superbot clients wire [client]` routes a client: it reuses that client's live relay key or mints one, and writes the local base URL and key into the client's config. - Caller key mint: `superbot keys mint ` and the relay app's Remote API page, **Mint new key**, mint caller keys `sbc_…` on your account. The raw key shows once. A caller key works on the hosted base and on the local base URL. The Remote API key is an agent key: its tools run on this computer, and the edge picks who pays. The CLI takes `--mode` and `--route`; without them the edge's defaults apply. - Failover between your sign-ins: the relay answers from your own vendor sign-ins, pooled per vendor. On 401 or 403 that sign-in is re-minted and the call moves to a sibling. On 429 it moves too. Each request makes at most 3 attempts, or one per sign-in when the vendor's pool holds more, up to 8. - Bare model: `superbot` or `auto`. Chat goes to `superbot-omni`. Code goes to Claude Code's default model on the Anthropic plan. - Own keys in connected apps: when the Helper wires an app, a key already in that app's config is kept and registered as a seat. Shapes: `sk-ant-…` (Anthropic), and `sk-…`, `sk-proj-…`, `sk-svcacct-…` or `sk-admin-…` (OpenAI). Not adopted: `sk-ant-oat…` (Anthropic OAuth tokens), `sk-or-…`, `AIza…` and `xai-…`. - Extra listen addresses: relay app, Overview, Endpoint card, **Also listen on**, **Add address**. Host: an IPv4 address. Port: 1024 to 65535. `0.0.0.0` needs allow-all. - On an extra address: the Host header must equal that IPv4 (else `421 host_not_allowed`); every route needs a key; lane keys answer `403 lane_key_loopback_only`; the Origin header must be on the allow-list; the `/v1` routes and `/mcp` are served. ```bash curl http://127.0.0.1:18787/v1/chat/completions \ -H "Authorization: Bearer sk-superbot-…" \ -H "Content-Type: application/json" \ -d '{"model": "superbot", "messages": [{"role": "user", "content": "Summarize this thread."}]}' ``` #### Secret references - Form: `{{secret:}}`, or `{{secret:.}}` with `password`, `secret` or `value` as the field. - The `` is a custody row id, written `kind:adapter`. - A reference expands only after the user approves the call. - The first use of a credential in a session raises one consent card. An Allow holds for the rest of that session. - A secret never expands into a file inside a git work tree. That call is refused. - Output values are scrubbed to `[redacted]`. #### Shell-safety switches - Location: Settings > Advanced, Relay group. - **Sandbox agent shell commands**: writes stay in the project and temp. On Windows, the row says macOS and Linux only. - **Guard shell prompts and sudo**: asks before sudo runs. - Both are off by default. - An agent cannot set either one. `hub__settings_set` refuses both, true or false. ### Discovery and access #### Discovery documents | Path | Holds | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | /llms.txt | the entry point: an agent fetches it and follows the recipe for its own client | | /docs.md | this page as markdown | | /docs/llms.txt | llms.txt for the API | | /docs/llms-full.txt | every API operation as markdown | | /docs/openapi.json | OpenAPI 3.1 | | /docs/openapi-3.2.json | OpenAPI 3.2 | | /.well-known/api-catalog | RFC 9727 linkset: the specs and the reference | | /.well-known/mcp/server-card.json | the MCP server card: name, endpoint, sign-in and tool list. Public, no key needed. The endpoint /mcp still needs a sign-in. | | /mcp/server-card | the same server in the standard MCP server card shape: name and endpoint, no tool list. Public, no key needed. | | /.well-known/ai-catalog.json | the AI catalog that lists that card. Public, no key needed. | | /.well-known/superbot-endpoints | the canonical origin, keyless. 404 when the deploy names none. | | /developers/.md | one API group as markdown | | /developers//.md | one operation as markdown | #### Sign-in and access answers | Request | Answer | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | https://superbot.gg/mcp with no key | 401 unauthorized, with a WWW-Authenticate: Bearer resource_metadata=… challenge pointing at /.well-known/oauth-protected-resource | | signed in, no beta grant | 403 no_beta_grant (signing in on the website grants it: sign-up is open) | | a gated page, in a browser | 302 to /invite?next= to sign in (sign-up is open, no invite needed), then back to | ## Features Each feature has one section: what it does and how to use it. ### Desktop and phone apps The desktop and phone apps run on one account, so a chat you start on one device keeps going on the other. 1. Download the app on each device from [Download superbot](https://superbot.gg/download). 2. Sign in with the same email on both. The **Sync chats across devices** switch in **Settings > Privacy** stores your chats on superbot's servers so your other devices see them, and **Sync projects across devices** turns project sync on or off. **Sync now** on a project pushes it at once. ### superbot relay The API key for your Subscriptions The superbot relay app switches the engine behind `claude`. 1. Install it from [Install](https://superbot.gg/docs#install). 2. Turn on **Omni runs claude** under **Options**, or run `superbot engine on`. Until then, `claude` runs Claude Code. 3. Run `superbot engine off` to go back. `superbot engine restore` puts your original launcher back exactly, as uninstall does. The launcher takes Claude Code's `claude` slot and never renames or edits its binary. With Omni on, only one-shot `claude -p` calls with known flags run on it. Everything else, and every call while the Helper is down, runs Claude Code. Agent SDK apps run on Claude Code. Set `cli_path` (Python SDK) or `pathToClaudeCodeExecutable` (TypeScript SDK) to use the launcher. The Helper serves your Claude, ChatGPT, Gemini, Grok, Muse Code, Kimi Code and GLM Coding Plan subscriptions at the local base URL `http://127.0.0.1:18787/v1` for any app with an OpenAI or Anthropic base URL, using a superbot relay key or a caller key. An app's own Anthropic or OpenAI key is kept and joins the pool. Seats of one vendor are shared; a seat at its limit hands the call on. See [superbot relay local API](https://superbot.gg/docs#relay-api). ### The Helper and CLI The Helper pairs your computer to your account, and you control it with the `superbot` command. 1. Run `superbot signin`. It opens your browser to pair the computer. 2. Run `superbot status` to see what the Helper is doing. 3. Run `superbot session` to chat with your agent in the terminal. `superbot keys mint ` prints a new `sbc_` caller key and shows it once. The desktop app carries the app's own update; `superbot update` updates the Helper alone. `superbot uninstall` asks first, then removes the Helper and the desktop app along with the data they hold on this computer. `superbot uninstall --dry-run` lists what would go without deleting anything. `superbot clients list` shows your AI clients and whether each is routed, and `superbot clients wire|unwire` routes one or stops it. `superbot keys list|revoke ` lists or revokes caller keys. `superbot mcp list` shows your MCP servers. `superbot engine status|on|off|restore` runs the engine switch. Related: [Uninstall](https://superbot.gg/docs#uninstall) ### Your AI clients Each AI client connects to superbot with its own recipe. 1. Open your client's recipe below. 2. Restart the client and ask what superbot tools it has. The answer includes `superbot`. The recipes cover [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). A client with no recipe connects with an API key or points its base URL at the Helper on this computer. [Your connection](https://superbot.gg/docs#connection) lists the hosted base URL and models, and [Keys and authentication](https://superbot.gg/docs#api-auth) covers the key. To send a client's model calls through superbot, switch it on under Your apps in superbot relay. An MCP client connects to the connector at `https://superbot.gg/mcp` (see [MCP server and its tool](https://superbot.gg/docs#tool)), and reaches your own tools at `https://api.superbot.gg/v1/mcp` through [Remote MCP](https://superbot.gg/docs#remote-mcp). Related: [Set up your clients](https://superbot.gg/clients) ### Super mode and swarms One message goes to a team of agents that run on your connected subscriptions and report what each one cost. - In the composer, set **Super** to **On**. The phone has the same toggle. - In `superbot session`, type `/super on`. Each agent narrates its plan and posts an update at each milestone. ### Daemon mode and parked chats An agent keeps watching on a schedule while you are away, and a parked chat waits for one thing before it carries on. #### Daemon mode 1. Open the composer's mode menu and choose **Daemon**, or type `/daemon` followed by what to watch. 2. Send your message to start the watch. A daemon watches up to 5 chats at once. 3. Use **Pause** and **Resume** in the status line under the composer. 4. To stop, choose **Agent** in the mode menu or type `/daemon` again. On the phone, the Options sheet has the same **Daemon** row, and the desktop app runs the checks. #### Park and resume When an agent has to wait, it parks the chat, and superbot wakes it when the wait is over. A banner above the composer reads **Parked:** with what the chat waits for. - **Resume now** wakes the chat at once. - **Cancel wait** drops the wait. On the phone, the same banner shows **Resume now** and **Cancel wait**. Related: [Fleet board](https://superbot.gg/docs#fleet) ### Fleet board One screen lists every agent working for you, on all your devices and in the cloud. 1. Open **Fleet** from the command palette or the **View** menu, or press `⌘⌥F` on a Mac or `Ctrl+Alt+F` on Windows. 2. Find a row under **Needs you**, **Running**, **Waiting** or **Done**, and press it to open its chat. 3. Press **Stop** on a running row to end its turn or cloud run. On the desktop, filter the board by **App**, **Project** or **Device**. On the phone, open Settings, then **Your agent**, and under **General** open **Fleet**. ### Plan card, race and checkpoints An agent shows its plan before it changes anything, and checkpoints rewind a bad result. #### Plan card 1. Choose **Plan** in the composer's mode menu, or type `/plan` followed by your request. 2. Press **Build** on the plan card to carry it out. #### Race **Build in parallel** runs the plan on up to four coding agents installed on this computer, each in its own copy of the project. Press **Merge this** on the column you want to keep, or **Stop race** to cancel. #### Checkpoints Checkpoints snapshot the chat and the project each time you send a message. They are on by default. 1. Hover a message of yours and press **Revert to here**. 2. Choose **Revert chat and files**, **Revert chat only** or **Restore files only**. 3. Press **Undo revert** to bring the messages back until your next message. The switch is **Checkpoints** in **Settings > General**, in the **Advanced** fold. On the phone, a revert restores files through the desktop app while it is online. #### Branch a chat Type `/branch` or `/fork` to copy the chat into a new one and switch to it. To cut at an earlier reply, hover it and press **Branch**. ### Automations An automation runs a standing instruction on a schedule you describe once, such as every weekday at 07:00. 1. Describe it in any connected client, for example "every weekday at 07:00, summarise my inbox". 2. Say "list my automations", or name one and say "pause it", "resume it", "change it" or "delete it". superbot stores the automation and delivers each result by text message or push. An automation runs on superbot's servers, so your computer does not need to be on. On the desktop, open **Settings > Automation** and press **New automation**. **Run now** runs a saved automation once. On the phone, open Settings and tap **Automation**. ### Context and imported chats superbot sends each chat to the model as you wrote it, and your account remembers the preferences you state. - A preference you state once applies in later sessions on all your devices. - When a chat runs on Claude, Anthropic clears old tool results on its side once the chat grows long, and the context meter shows what it cleared. - Chats you import from other apps are stored on superbot's servers, and superbot searches and summarises them when you ask in a connected client. Related: [Import chats from other apps](https://superbot.gg/docs#import), [Tidy mode](https://superbot.gg/docs#tidy) ### Tidy mode Tidy keeps each turn short by pasting in the rules and skills your task needs and linking the rest. Tidy is on by default. 1. Open **Settings > Library**, then open **Advanced**. 2. Under **How rules are sent**, **What each task needs** is Tidy. Choose **Everything, as written** to undo Tidy. 3. Press **Per app** to choose for one app at a time. 4. Press **Show** beside **What changed** to see each rule Tidy cut or trimmed. The **Tidy** switch above **How rules are sent** is a separate setting. It merges duplicate global items into one copy. In one benchmark run, Tidy sent 77% fewer rule tokens on the first call than sending your full setup. Tools and the system prompt are not counted. On the phone, open Settings, then **Your agent**. Under **Library**, open **Advanced** and find **How rules are sent**. ### Import chats from other apps Bring the chat history you already have in other AI apps, such as ChatGPT, into superbot, where it shows in that app's **Chats** list. Imported chats are stored on superbot's servers and readable by superbot. 1. On the desktop, open **Settings > Privacy** and tick the app under **Chats**, or turn on **Vendor chats** for every app. 2. Press **Add** in the sidebar, then **Connect an app…**, and pick the app. 3. For an app that keeps its chats on your computer, press **Import chats**. On an app's **Chats** list, **Resync** scans again, and **Choose a file…** imports a data export when the app offers one. On the phone, open History, press **Import a shared chat**, paste a ChatGPT or Claude share link and press **Import**. Related: [Context and imported chats](https://superbot.gg/docs#context) ### MCP server and its tool Any MCP client that connects to superbot gets one tool, `superbot`, that takes a search, a lookup of one tool, or a request in plain words, and does the work. [MCP endpoints](https://superbot.gg/docs#mcp-endpoints) has the endpoint details. To connect one client straight to the server, ask a coding agent to install the superbot MCP server globally, then to install the superbot skill globally. `install the superbot MCP server globally: https://superbot.gg/mcp install the superbot skill globally: https://superbot.gg/skills/superbot/SKILL.md Tell me if I need to sign in.` Then type `/superbot` in your agent. In Codex, type `$superbot`. No account yet? Your agent follows [/auth.md](https://superbot.gg/auth.md). Claude Code also has a link install with no sign-in step: one `curl` request to the server's `/install` address, with `client=claude-code` in its body, gets back an `add` command that carries its own key, and a `link_url` the account owner approves. The server URL is under [Your connection](https://superbot.gg/docs#connection). Codex has one too, with `client=codex` in its body, which gets back a `config_toml` entry with its own key instead. The OAuth fallback is `claude mcp add` with the server URL, then a sign-in from `/mcp` in a new session. `claude mcp add --transport http superbot https://superbot.gg/mcp -s user` No browser? Signed in, [copy a key](https://superbot.gg/download#mcp). Then ask for something in plain words, such as "summarise my unread email", and the client calls `superbot` with your words. Related: [Your AI clients](https://superbot.gg/docs#clients) ### Your own MCP tools, remotely Call your own MCP tools from any remote MCP client. Send a POST request to: `https://api.superbot.gg/v1/mcp` Send your account key, which starts `sbk_`, or an API key with the MCP tools scope, which starts `sbc_`. The switch is **Allow remote MCP tools**, on the MCP page of the superbot relay app under **Your tools, remotely**. It is off by default on each computer, and only you can turn it on. Tool names read `__`, and the Helper's own tools are never offered. [MCP endpoints](https://superbot.gg/docs#mcp-endpoints) lists the endpoints. Add an entry like this to your client's MCP settings: ```json { "mcpServers": { "superbot-tools": { "type": "http", "url": "https://api.superbot.gg/v1/mcp", "headers": { "Authorization": "Bearer sbk_..." } } } } ``` The superbot tool at `https://superbot.gg/mcp` is a different endpoint and stays one tool named `superbot`. Related: [Your MCP servers](https://superbot.gg/docs#mcp-servers), [Keys and authentication](https://superbot.gg/docs#api-auth) ### Your MCP servers superbot installs and checks the MCP servers your agents use. 1. Ask for the capability in plain words, for example "add a Linear tool". The agent searches MCP registries and offers the best match. 2. Approve the install when the agent asks. 3. On the desktop, open **Settings > Tools & MCP** to see every server and whether it works. **Add a tool** adds one by hand, by **HTTP URL** or **Command**. A row that needs you has an action such as **Sign in** or **Approve change**. If an installed server later changes a tool, its tools stay held back until you press **Approve change**. On the phone, open Settings, then **Connections**, and find **Tools & MCP**. From a terminal, `superbot mcp list` shows each server's state and tool count, and `superbot mcp remove ` removes one. Related: [MCP server and its tool](https://superbot.gg/docs#tool) ### Built-in tools Every agent starts with the same tools, so one ask can research a topic and hand back a finished file. - **Web** search and page reading, with a browser for pages that need JavaScript and web archives for pages that are gone. - **Research** searches scholarly papers and code repositories, and writes a cited report. - **Files** builds a spreadsheet with live formulas, a document, a deck or a PDF. - **Media** makes pictures, video, audio and 3D models from a description. - **Browser and screen** works sites you are signed into and, when you allow it, any app on your screen. Related: [Your browser and your screen](https://superbot.gg/docs#computer), [Pictures, video, audio and 3D](https://superbot.gg/docs#media) ### Browser sessions and logins Your agent works the sites you are signed into, using sessions the Helper reads from your own browsers. 1. Sign in to the site in your browser. 2. Ask your agent to use the site. The Helper reads your browsers only after you allow it. On a Mac it reads Chrome, Brave, Edge, Arc, Vivaldi, Firefox and Safari. 3. To import one site yourself, run `superbot cookies `. Add `--dry-run` to write nothing or `--yes` to skip the prompt. Saved logins import from your browsers and from 1Password, Bitwarden, LastPass and KeePass. To switch a read off, open **Settings > Privacy** and use **Browser sign-ins** or **Passwords and SSH keys** under **What Superbot can read on this computer** (**this Mac** on a Mac). ### Your browser and your screen Your agent browses websites for you, for example to order food, and with your permission works any app on your screen. On the desktop, the chip in the **Browser** pane's address bar picks where agent pages open: **Cloud**, or **This Mac** (**This computer** on Windows). **My IP** sends the cloud browser's traffic out through your computer's connection, so sites see your own address. Computer use works on Mac and Windows and has three settings. **Off** never touches your screen, **Ask** asks before each action, and **Always** acts without asking. It starts at Off. 1. Press the computer use toggle in the composer to move through **Off**, **Ask** and **Always**. 2. On a Mac, the first time, **Turn on computer use** asks for **Accessibility** to click and type and **Screen Recording** to take screenshots. On Windows, there is no system permission to grant: the first screen action shows the inline Allow card instead. When it is Off and a task needs your screen, the agent asks **Turn on computer use: **. Choose **Allow in this chat**, **Always allow** or **Not now**. Related: [Download superbot](https://superbot.gg/download) ### Live view and remote control From another device, you watch the screen of the device that did your task and take its controls. 1. From one device, ask another to do something, for example from your phone to your computer. The reply shows a tile with **Watch live**. 2. Press **Watch live**. The other device opens as live video. 3. Choose **Observe** to watch or **Control** to click and type. **End** closes the viewer. The viewed computer shows a banner naming the device, with **Stop Sharing**. To change what it allows, open **Settings > Privacy** and find the **Live view** group: - **Let your other devices view and control this computer** turns Live view on or off. It is on by default. - **Require approval on this computer** asks on this computer before another device can view or control it. It is off by default. A device you have not allowed opens view only. Press **Allow** on the viewed computer, then reconnect to take control. A device added to your account in the last 24 hours starts this way. ### Pictures, video, audio and 3D superbot makes pictures, video, audio and 3D models on its own account, so you connect nothing first. - **Pictures** appear in the chat, from a description. - **Video** is a short clip, from a description or a picture. - **Audio** is a song, a sound effect or a spoken voice line. - **3D** is a model file, from a description or a picture. On superbot's account each result costs credits, and each kind has a daily limit. A sign-in or key of your own is used first when you have connected one, and it spends no credits: your ChatGPT plan or your OpenAI, Gemini or Grok key for pictures, your OpenRouter, Google or xAI key for video, and your OpenAI or Gemini key for audio. A ChatGPT Free plan cannot make images, so superbot tries your key next. Every result says which account paid. When your own sign-in or key could not be used, it says why. Connect accounts in **Settings > Subscriptions & keys**. On the phone, open **Settings > Connections**. Related: [Credits](https://superbot.gg/docs#credits) ### Calls and texts from your phone Your agent calls and texts people from your own iPhone number, and a text to superbot's own number gets its answer back as a text. This needs a Mac with the Helper running, an iPhone paired to it, and Messages signed in to your Apple Account on the Mac. 1. Open **Settings > Tools & MCP**. At the bottom, under **Phone line**, the chip reads **Calls and texts from your iPhone** when setup is done. 2. Finish the setup it lists: **Allow Messages**, then **Open Full Disk Access**. For calls, also choose **Superbot Call Mic** as the microphone in Phone. 3. Ask: "call the dentist and ask for the first free slot". Every call and text asks you first. If Phone.app needs it, you tap **Call** once on your Mac. The same number is called at most once in 24 hours. **Open calls…** under **Phone line** lists what your agent made. To text superbot, text its number: the **Text Superbot** card under **Phone line** on **Settings > Tools & MCP** shows **Text to link a phone**. On the phone, open Settings, then **Connections**, and under **Phone line** open **Text Superbot**. Related: [Text Superbot](https://superbot.gg/sms), [Endpoints](https://superbot.gg/docs#api-endpoints) ### Text Superbot by SMS Superbot answers questions and runs tasks over SMS. Text its number from any phone to start. - **Text** +14157180220 from any phone. No purchase or app install is required. - **Your first text** is your opt-in. Superbot texts you back. - **Link a Superbot account** by SMS, and you get a one-time confirmation text. - **Reply STOP** to opt out, or **HELP** for help. Message frequency varies, and message & data rates may apply. Related: [Text Superbot](https://superbot.gg/sms), [Calls and texts from your phone](https://superbot.gg/docs#voice) ### Voice chat and dictation Talk to an agent and hear it answer, or dictate a message instead of typing it. #### Voice chat 1. On the desktop, press **Voice** in the composer, or choose **Start voice chat** in the File menu (`⌘⇧O` on a Mac, `Ctrl+Shift+O` on Windows). On the phone, press **Voice** in the composer. 2. Talk. The control shows what is happening, from **Listening** to **Speaking**. 3. Press **End voice** to finish. To use your own voice, open **Settings > Voice**, press **Record my voice** under **Your voice**, read for up to 60 seconds, tick **My voice, or I have permission**, then choose **My voice**. The sample goes to ElevenLabs and the voice is AI-generated. #### Dictation 1. Press the microphone in the composer (**Click to speak**) and talk. It reads **Listening. Click to stop.** 2. The text lands in the message box, ready to edit. 3. To choose where speech becomes text, open **Settings > Voice** and set **Dictation engine**. **On this Mac** (**On this computer** on Windows) keeps the audio on it, and **Superbot cloud** sends it to the speech provider. ### Quick Ask On the desktop, one shortcut opens a small panel from any app that answers about the window you were using. 1. Press `Alt+Space` (`⌥Space` on a Mac) from any app, or choose **Quick Ask** in the File menu. 2. Type your question under **Ask anything**. A chip shows the app and window you came from. 3. Press **Expand to full chat** to carry on in the full app. Escape hides the panel and keeps your draft. Quick Ask attaches a screenshot only when you press **Screen snapshot**. To change the shortcut, open **Settings > Shortcuts** and press **Record** in the **Quick Ask** group. **Restore default** goes back. ### Build, edit and preview On the desktop, you run a live copy of what your agent builds and change its files without leaving the app. 1. Press **Preview** in the project header, beside **Publish**. The app runs the project on your computer and opens it in the side pane. **Stop** ends it. 2. Open a project file to edit it. **Save** writes it, **Format** formats it, and **Diff** and **File** switch the view. 3. For a page or document the agent made in a chat, press **Open in pane**. In the pane, **Edit** changes it in place and **Done** finishes. **View code** shows the source and **Download** saves it. Related: [Publish your app](https://superbot.gg/docs#publish), [Download superbot](https://superbot.gg/download) ### Publish your app Your app goes online at a free `.superbot.sh` address on your own Cloudflare account. This needs a free Cloudflare account. The first time, **Connect Cloudflare** opens a dialog: press **Continue to Cloudflare**, sign in, then pick **Use this account**. 1. Open a project and press **Publish** in its header. 2. Pick a name. Under **Who can open it?** choose **Anyone** or **Only people I invite**. 3. Press **Put it online**. Publish checks the app and tests it on your computer first. Later publishes read **Update live app**. Once it is live, the **Live** tab on the project manages it. **Versions** keeps every publish and **Roll back** returns to an older one. **Domains** renames the address or adds your own. **Keys** stores the secrets your app reads. **Remove app**, under **Take it offline**, deletes the app and its data for good. Type `/publish` in a chat to have your agent publish the project. Related: [Build, edit and preview](https://superbot.gg/docs#build), [Download superbot](https://superbot.gg/download) ### Cloud runs from your phone Your phone sends a task to a cloud copy of your project, and the files it changes sync back to your computer. This needs **Sync projects across devices** on in **Settings > Privacy**, under **Advanced**, and sync on for the project. Without it the phone says **Turn on sync to work in the cloud.** 1. On the phone, open a chat in the project and press **Run in cloud** in the thread header. 2. The next time the Helper syncs, the changed files land in your local folder. On the desktop, press **Build in cloud** on the plan card. It stays off until the project is linked to a repo, with the reason **Link a repo to this project first**. In a repo-linked project, if you edited a file the cloud also changed, yours stays and the cloud's version lands beside it as `notes.sync-conflict-20261004-101500-cloud.md`. Related: [Download superbot](https://superbot.gg/download) ### Phone extras On iPhone, you start a chat from the home screen or the Action Button, and the Lock Screen shows a running agent. - **Home-screen shortcuts**: press and hold the superbot icon for **New chat**, **Ask by voice** and **Voice chat**. - **Action Button**: in the iOS Settings app, open **Action Button**, choose **Shortcut**, then pick **New chat** or **Start voice chat** from superbot. - **Lock Screen and Dynamic Island**: show **Superbot is working** while an agent runs and **Waiting for you** when it needs you. - **Notifications**: in Settings, on **Your agent**, under **General**, switch **Push when Superbot finishes** and **Push when Superbot needs you**. Both are on by default. - **Offline reading**: chats stay readable on the phone without a connection. Related: [Voice chat and dictation](https://superbot.gg/docs#voice-chat), [Download superbot](https://superbot.gg/download) ### superbot-omni superbot-omni is superbot's own agent loop: it sends your turn to the model, runs the tools it asks for and repeats until done. It drives any model behind the OpenAI or Anthropic API with the same tools, including the models on your custom endpoints. To compare two models, pick each in the model picker and send the same task. Related: [Custom endpoints](https://superbot.gg/docs#external-apis), [Models](https://superbot.gg/docs#api-models) ### Teams and policy A team shares MCP servers, rules and skills across its members and applies one signed policy to every member's devices. 1. Open **Account > Teams** and press **Create team**. 2. Under **Members**, enter an email, pick a role below your own and press **Invite**. 3. Owners and admins see the **Policy and coverage** card. It reads a count such as **3 of 5 reported** once a policy is published, and marks a member whose devices have not reported as **not reported**. An owner or admin publishes the signed policy through the org API. Until then the card reads **No policy published yet.** Related: [Teams and enterprise](https://superbot.gg/teams) ### Usage and spend See what your agents used and what it cost, for the last 7 days by default. Open **Account > Usage** to read it, and pick a longer range there. To cap a caller key, set **Daily limit** or **Monthly limit** in credits when you mint it under **Account > API**. A key that reaches a limit is refused until the window resets. Related: [Keys and authentication](https://superbot.gg/docs#api-auth), [Endpoints](https://superbot.gg/docs#api-endpoints) ### Custom endpoints Add any OpenAI- or Anthropic-compatible endpoint to the model picker and dial it with your own superbot key beside the house models. 1. Open **Settings > Subscriptions & keys** and find the **Custom endpoints** group. 2. Press **Add endpoint** (**Add an endpoint** on an empty list). 3. Under **Where it is saved**, pick **Hosted endpoint** so every device on your account can dial it, or **This Mac** (**This computer** on Windows) to keep it on this computer. 4. On the hosted path, enter a **Label**, the **Base URL** and the **API key**. 5. Set **Dialect** to **Auto**, **OpenAI** or **Anthropic**, then press **Add endpoint**. Models load when the endpoint answers `/models`, and **Refresh models** reloads them. **Scan for keys**, under **Found on this Mac** (**Found on this computer** on Windows), finds API keys already on this computer and offers each one as an endpoint. On the phone, open **Settings > Connections** and choose **Custom endpoints**. Related: [Models](https://superbot.gg/docs#api-models), [Keys and authentication](https://superbot.gg/docs#api-auth) ## API Call the same agents the app uses over HTTP, with a caller key you mint and can revoke. ### Keys and authentication A caller key starts with `sbc_` and belongs to your account. #### Key kinds | Key | Prefix | What it does | | ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Caller key | sbc\_ | Minted under **Keys**, by superbot keys mint , or by the relay app's Remote API page. Its own **Spend from**, **Mode** and **Models** settings apply. Also accepted by the relay on the local base URL while the relay is on. | | Account key | sbk\_ | One per account, shown as **Account key** on **Account > API**. Rotating it stops every client on the old key. Accepted on https://api.superbot.gg/v1/mcp and, while the relay is on, on the local base URL. The hosted model routes answer 401 to it; send a caller key. An agent with no account follows [/auth.md](https://superbot.gg/auth.md), which signs its user in and mints a caller key with this key. | | Saved provider key | the vendor's own key | Saved under **Providers** on **Account > API**. Sent as-is, it runs that vendor only, as a single model call. GET /v1/models lists that vendor only. x-superbot-route and x-superbot-mode are ignored. | | Relay key | sk-superbot- | Minted when the Helper wires a client. Works on the local base URL http://127.0.0.1:18787/v1 and on any extra address the relay listens on. The hosted base URL answers 401. See [the local relay API](https://superbot.gg/docs#relay-api). | #### Mint a key 1. Open **Account > API**, find **Keys** and select **New key**. 2. Enter a **Name** of up to 64 characters. 3. Set the fields you need. 4. Select **Create key**. 5. Copy the key. The page shows it in full only once. To edit a key, select its row under **Keys** and change the fields below. To revoke a key, select **Revoke** on its row under **Keys**. It stops working immediately. #### Key settings | Field | Choice | Effect | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | **Access** | **Models** (default) | calls models; reads usage and the credit balance | | **Read-only query** | reads your account; calls no model | | | **Full access** | holds every scope listed under **Scopes** | | | **Spend from** | **Your providers** | uses your own vendor accounts; spends no credits | | **Credits** | spends your credit balance | | | **Auto** (default) | uses your providers when the account holds a credential for the model's vendor, a custom endpoint, or an online Helper holding it; otherwise credits | | | **Daily limit** | credits | caps the key's spend over any 24 hours; empty means no cap | | **Monthly limit** | credits | caps the key's spend in a calendar month (UTC); empty means no cap | | **Mode** | **Single model call** (default) | Goes straight to the model. For Cursor, SDKs, scripts. | | **Full agent turn** | Superbot's agent does the task. For phones and chat apps. | | | **Models** | comma-separated ids | \* matches any run of characters and ? one character; empty means all | | **Incognito** | checkbox | keeps the key's turns out of your history | | **Scopes** | one checkbox per scope | ticking any box replaces **Access**; a write scope includes its read | #### Send a key The key goes in the `Authorization: Bearer` header. `x-api-key` carries the same key for clients that expect it. ```bash curl https://api.superbot.gg/v1/models \ -H "Authorization: Bearer sbc_…" ``` Related: [Set up your clients](https://superbot.gg/clients), [Account](https://superbot.gg/account) ### Routing by key One base URL serves every key. The key sets what answers. Set the base URL and key as shown under [Send a message](https://superbot.gg/docs#api-endpoints). #### What runs per key | Key | What runs | Spends | | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | Caller key, no provider saved, no custom endpoint, no Helper online | house models; priced vendor models | credits | | Caller key, with a provider saved, a custom endpoint, or a Helper online | vendor and subscription ids on your own accounts; device ids on your computer, through the relay; house models | your accounts and computer; credits for house models | | Saved provider key | that vendor's ids only, as a single model call | your vendor account | Subscription ids run on a Claude Pro/Max, ChatGPT/Codex, Gemini Code Assist or SuperGrok sign-in. Device ids are the `ollama/`, `lmstudio/`, `omlx/` and `openrouter/` ids a live device holds. #### Per route | Route | Vendor id, held | Vendor id, nothing held | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | auto (default) | runs on the held credential, a custom endpoint or a live device; a credential only a device can open, with no device online, goes to credits | credits | | byo | runs on the held credential, a custom endpoint or a live device; a credential only a device can open, with no device online, answers 403 no_vendor_credential, reason device_required | 403 no_vendor_credential, unless a custom endpoint serves the id | | credits | credits only | credits only | Held means the edge can open a saved sign-in or key for the vendor, a custom endpoint, or a live device that holds the vendor. Nothing held means none of those three. #### Per request | Header | Values | Effect | | ---------------- | ------------------ | ------------------------------------------------------------------------------------ | | x-superbot-route | byo, credits, auto | overrides a caller key's **Spend from** for one request; any other value answers 400 | | x-superbot-mode | model, agent | overrides the key's **Mode** for one request | - `superbot`, `superbot-omni` and `superbot-fast` always run a full agent turn, whatever `x-superbot-mode` says. - A saved provider key ignores both headers and cannot name those three ids (`403` `model_not_allowed`). #### Device and list rules - On `byo`, a credential only a device can open (a sign-in or key sealed to your devices) answers `403` `no_vendor_credential`, reason `device_required`, when no device that can serve it is online. There is no credits fallback on `byo`. - On `auto`, the same credential with no device online goes to credits. With a device online, the call is routed to that device. - `GET /v1/models` with the key is the authoritative list of what the account can call. Credits rows carry `available`; a `reason` is set when one applies. ### Models `GET /v1/models` lists every model id the account can call, whether or not the key's **Models** names it. A saved provider key lists only its vendor's ids. A call to an id the key's **Models** does not name answers `403` `model_not_allowed`. #### Model ids | Form | Spelling | Runs on | | --------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Agent id | superbot, superbot-omni, superbot-fast | the house agent turn. superbot-flash is the old alias of superbot-fast. | | Vendor id | /, or the vendor's bare id | the vendor credential the route picks, or credits on auto | | Subscription id | the vendor's bare id, as GET /v1/models lists it for that sign-in | the account's own sign-in, as listed under [Routing by key](https://superbot.gg/docs#api-routing) | | Custom id | custom//, or custom/ resolved through the endpoints' model lists | that custom endpoint | | Device id | ollama/, lmstudio/, omlx/, openrouter/ | the user's computer, through the relay, while a live device holds it | Each `GET /v1/models` row that knows its window carries `context_length`, with the same value in `context_window`. Agent ids always carry one. #### House models `superbot`: Your Superbot agent. Context window: 1M. `superbot-omni`: Superbot agent, run on your computer. Context window: 1M. `superbot-fast`: Quick and cheap, for small jobs. Context window: 500k. __house model rates__ | Model | Input | Output | Cache write | Cache read | Use | | ------------- | ----------- | ----------- | ----------- | ---------- | ------------- | | superbot | 1,000 $1.00 | 5,000 $5.00 | 1,250 $1.25 | 50 $0.05 | API and MCP | | superbot-fast | 1,000 $1.00 | 5,000 $5.00 | 1,250 $1.25 | 50 $0.05 | API and MCP | | superbot | 200 $0.20 | 1,000 $1.00 | 250 $0.25 | 10 $0.01 | Superbot apps | | superbot-fast | 200 $0.20 | 1,000 $1.00 | 250 $0.25 | 10 $0.01 | Superbot apps | Credits per 1M tokens, with dollars beside them; one credit is $0.001. Calls with your API key bill at the API and MCP rate. In the Superbot apps, superbot and superbot-fast both bill at 20% of the API and MCP rate. Neither model is free on either lane. Fast mode bills 2x every rate. Reasoning tokens bill as output. #### Effort and Fast `superbot` serves the efforts `none` (no reasoning), `low`, `high` and `max`, and runs at `high`, its default, when the request names none. `low` reasons less than `high`, and `max` reasons the most. `superbot-fast` runs at `low`, or `none`. Send the effort in the request's own field: `reasoning_effort`, `reasoning.effort` or `output_config.effort`. Other levels are served as one superbot runs: | You send | Served as | | --------- | --------------------------- | | minimal | low | | medium | low | | xhigh | high | | ultra | max | | no effort | high (low on superbot-fast) | Fast serves the turn on the faster tier at twice the price. Ask for it with `service_tier: "priority"` or `"fast"`, with Anthropic's `speed: "fast"`, or with the header `x-sbr-speed: fast`. `GET /v1/models` lists each house model's `reasoning_efforts`, `default_reasoning_effort` and `service_tiers`. Asked in Anthropic's shape (with an `anthropic-version` header), each house row carries `max_input_tokens` and `capabilities.effort` instead, and with `?client_version=` the list is Codex's own model catalog. #### Other models Vendor model ids run on your own accounts and keys, or on credits. An endpoint added with **Add endpoint** under **Providers** on **Account > API** appears as `custom//`, for example `custom/example/llama-3.3-70b`. Related: [Custom endpoints](https://superbot.gg/docs#external-apis), [Credits](https://superbot.gg/docs#credits), [The API page](https://superbot.gg/api) ### Endpoints Each route links to its reference on [/developers](https://superbot.gg/developers). A scope names what the key must hold. `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 | | ------ | --------------------------------------------------------------------------------------- | ----------------------------------------------- | -------------- | | GET | [/v1/turns/{session}](https://superbot.gg/developers/gateway/getTurn) | Read a turn | turns:read | | GET | [/v1/turns/{session}/stream](https://superbot.gg/developers/gateway/streamTurn) | Re-attach to a turn’s stream | turns:read | | 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 | | POST | [/v1/keys/{id}/rotate](https://superbot.gg/developers/keys/rotateKey) | Rotate 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/org/{id}/audit](https://superbot.gg/developers/teams/exportTeamAuditLog) | Export a team’s audit log | teams:read | | 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 | | ------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------- | | POST | [/v1/devices/{device_id}/jobs](https://superbot.gg/developers/devices/createAgentJob) | Run a job on an agent computer | devices:write | | GET | [/v1/devices/{device_id}/jobs/{job_id}](https://superbot.gg/developers/devices/getAgentJob) | Read an agent computer job | devices:read | | GET | [/v1/devices/{device_id}/terminals/{terminal_id}/stream](https://superbot.gg/developers/devices/streamAgentTerminal) | Stream an agent computer terminal | devices:read | | GET | [/v1/pair/{user_code}](https://superbot.gg/developers/devices/previewAgentPair) | Preview an agent computer code | any key | | POST | [/v1/pair/{user_code}/approve](https://superbot.gg/developers/devices/approveAgentPair) | Approve an agent computer code | any key | | POST | [/v1/pair/{user_code}/deny](https://superbot.gg/developers/devices/denyAgentPair) | Decline an agent computer code | any key | | 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 | #### Runs [Full reference](https://superbot.gg/developers/runs) __Runs routes__ | Method | Path | What it does | Scope | | ------ | --------------------------------------------------------------------------------- | --------------------------------- | ---------- | | GET | [/v1/runs](https://superbot.gg/developers/runs/listRuns) | List cloud runs | runs:read | | POST | [/v1/runs](https://superbot.gg/developers/runs/createRun) | Start a cloud run | runs:write | | GET | [/v1/runs/projects](https://superbot.gg/developers/runs/listRunProjects) | Find the project for a repository | runs:read | | GET | [/v1/runs/{run_id}](https://superbot.gg/developers/runs/getRun) | Get a cloud run | runs:read | | GET | [/v1/runs/{run_id}/events](https://superbot.gg/developers/runs/listRunEvents) | Follow a run’s events | runs:read | | POST | [/v1/runs/{run_id}/cancel](https://superbot.gg/developers/runs/cancelRun) | Cancel a cloud run | runs:write | | POST | [/v1/runs/{run_id}/messages](https://superbot.gg/developers/runs/sendRunMessage) | Steer a running cloud run | runs:write | Related: [Full API reference](https://superbot.gg/developers), [OpenAPI 3.1 spec](https://superbot.gg/docs/openapi.json) #### Send a message `POST /v1/chat/completions` takes an OpenAI Chat Completions body, `POST /v1/responses` an OpenAI Responses body and `POST /v1/messages` an Anthropic Messages body. Each answers in its own shape. ```bash export OPENAI_BASE_URL=https://api.superbot.gg/v1 export OPENAI_API_KEY=sbc_… export ANTHROPIC_BASE_URL=https://api.superbot.gg/v1 export ANTHROPIC_API_KEY=sbc_… ``` **curl** ```bash curl https://api.superbot.gg/v1/chat/completions \ -H "Authorization: Bearer sbc_…" \ -H "Content-Type: application/json" \ -d '{ "model": "superbot", "messages": [{"role": "user", "content": "Summarize this thread."}] }' ``` **OpenAI SDK** ```python from openai import OpenAI client = OpenAI(base_url="https://api.superbot.gg/v1", api_key="sbc_…") response = client.chat.completions.create( model="superbot", messages=[{"role": "user", "content": "Summarize this thread."}], ) print(response.choices[0].message.content) ``` **Anthropic SDK** ```python from anthropic import Anthropic client = Anthropic(base_url="https://api.superbot.gg/v1", api_key="sbc_…") message = client.messages.create( model="superbot", max_tokens=1024, messages=[{"role": "user", "content": "Summarize this thread."}], ) print(message.content[0].text) ``` #### Streaming Send `"stream": true` to any of the three routes to receive server-sent events in that route's own shape. ```bash curl -N https://api.superbot.gg/v1/chat/completions \ -H "Authorization: Bearer sbc_…" \ -H "Content-Type: application/json" \ -d '{"model": "superbot", "stream": true, "messages": [{"role": "user", "content": "Summarize this thread."}]}' ``` - Chat Completions sends `data: {"choices":[…]}` frames and ends with `data: [DONE]`. - Responses sends typed events such as `response.output_text.delta` and ends with `response.completed`. - Messages sends Anthropic's events, from `message_start` to `message_stop`. Usage and billing settle when the stream ends, and an aborted stream is billed for what it produced. #### Long answers without streaming A non-streamed call whose answer takes more than 30 seconds gets its `200` and `content-type: application/json` headers early, then a newline every 15 seconds until the JSON body follows. Any JSON parser skips that leading whitespace. If the call fails after those headers went out, the status stays `200` and the body is the route's error object (`{"error": {…}}`, or `{"type": "error", "error": {…}}` on Messages). Send `"stream": true` for long turns. ### Limits and errors #### Rate limit A caller key gets 1200 requests a minute. Over that, the route answers `429` before any model is called, with this body: ```json { "error": { "message": "per-key rate limit reached", "type": "rate_limit_error", "param": null, "code": "rate_limit_error", "retry_after": 12, "source": "account" } } ``` That is the Chat Completions and Responses body. On Messages the same refusal comes in Anthropic's envelope: `{"type": "error", "error": {"type": "rate_limit_error", "message": "per-key rate limit reached", "retry_after": 12, "source": "account"}}`. `retry_after` is in seconds. `source: account` says the limit is your key's own. The `x-ratelimit-remaining` and `x-ratelimit-reset` headers carry the same window. #### Errors Model routes answer in the caller's dialect, and the Field column says where each code sits. A top-level `error` is a string code. Account routes answer in that form too, with `message`, `doc_url` and `request_id` beside it. The two refusals of a body Superbot cannot take, `413` and `415`, are flat bodies with the code at the top level, in `code`. | Status | Field | Code | Meaning | | ------ | ---------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | error.code | invalid_json | the body is not a JSON object; error.type is invalid_request_error | | 400 | error.code | unknown_model | no vendor claims the model id; error.fix says how to pick one (see below) | | 400 | error.code | invalid_route_header | x-superbot-route is not byo, credits or auto; error.param is x-superbot-route | | 400 | error.code | no_user_message | an agent id was called with no user message to run | | 400 | error.code | house_key_protocol | the model runs on Superbot's own key, which takes only /v1/chat/completions, /v1/messages and /v1/responses | | 400 | error.code | invalid_service_tier | service_tier (or speed) is not a printable ASCII word; error.param is service_tier | | 400 | error.code | request_part_unsupported | the model cannot take a part of the request; error.message says why | | 400 | error.code | device_lane_dialect | the model runs on your computer, which takes only /v1/chat/completions or /v1/messages | | 400 | error.code | no_vendor_credential | reason code_assist_not_dialable: a Google Code Assist sign-in cannot be dialed; add a Gemini API key, or send x-superbot-route: credits | | 400 | error.code | no_vendor_credential | the saved credential for that vendor needs the /v1/responses shape; send the call there. vendor names the vendor | | 401 | error.type | authentication_error | the key is missing, malformed or unknown | | 401 | error.code | key_required | the same refusal with a code to branch on; error.message says where to send the key | | 402 | error.code | insufficient_balance | the credit balance cannot cover the call; error.message names the billing page to add credits (see below) | | 402 | error.code | daily_limit, monthly_limit | the key reached its own limit | | 403 | error.type | permission_error | the key is revoked | | 403 | error.code | key_revoked | the same refusal with a code to branch on; error.source is client | | 403 | error | insufficient_scope | the key lacks the route's scope; x-superbot-required-scopes names it | | 403 | error.code | model_not_allowed | the key's **Models** setting does not include that model | | 403 | error.code | model_not_allowed | a saved provider key named another vendor's model, or an agent id | | 403 | error.code | agent_not_granted | the n-agent header names an agent with no live grant | | 403 | error.code | no_vendor_credential | no usable sign-in or key for that model's vendor; byo_url links to where to add one | | 403 | error.code | no_vendor_credential | reason device_required: the credential is held only on a device whose Helper is offline; no credits fallback | | 403 | error.code | no_vendor_credential | reason device_only: a local runtime (omlx/, lmstudio/) whose device is not live | | 403 | error.code | no_vendor_credential | reason not_connected: no key or sign-in is saved for the vendor | | 403 | error.code | no_vendor_credential | reason oauth_not_routable: this sign-in kind is not routable | | 403 | error.code | no_vendor_credential | reason reconnect: the sign-in expired and could not be refreshed; sign in again | | 403 | error.code | no_custom_upstream | none of your custom endpoints serves that custom/ id; byo_url links to where to add one | | 413 | code | body_too_large | the body, or the body once its content-encoding is decoded, is over the route's size limit; max_bytes is the limit | | 415 | code | unsupported_encoding | the content-encoding is one Superbot cannot decode; encoding names it, and fix and supported_encodings say what to resend (see below) | | 429 | error.type | rate_limit_error | over the per-key rate | | 429 | error.code | caller_binding_refusal | every account this key can spend already serves its maximum number of callers; error.retry_after_ms is set | | 429 | error.code | account_stormed | the vendor account is repeating the same refusal; error.retry_after_ms is set | | 503 | error.code | budget_unavailable | the spend ledger cannot be read, so the call is refused before any dial | | 503 | error.code | device_offline, device_gone | the model runs on your computer, and that computer is not online; error.vendor names the vendor | | 504 | error.code | device_timeout | the model on your computer did not finish in time; the call may still be running there | | 5xx | error.type | api_error | the model provider or the agent turn failed | An error object can carry machine members beside `message` and `code`. They only add: a client that does not know a member ignores it, and a member never changes the status, `error.type`, `error.code` or message of the refusal. - `error.source` says whose side the problem is on: `request` (the request or conversation itself), `client` (your key, API shape or headers), `account` (your credits, plan, limits or saved keys), `superbot` (Superbot itself failed; a retry may help), `model_server` (Superbot's model service is down, overloaded or answered nothing) or `provider` (a provider you connected refused or failed). The set can grow, so ignore a value you do not know. - `error.fix` names the step that clears the refusal. On `unknown_model` it is `pick_listed_model`: `error.models_path` is `/v1/models`, and `error.accepted_models` lists up to three ids the key can call, never the one you sent. A key with no other id to offer gets no `accepted_models`. - The `415` carries `fix: resend_supported_encoding` at the top level, with `supported_encodings` listing the encodings Superbot decodes: `gzip`, `x-gzip`, `deflate`, `br` and, where the server supports it, `zstd`. A provider's own error passes through with the provider's status, marked by the `x-superbot-error-origin: vendor` header. #### Out of credit When the account behind a caller key has no credit left, the call answers HTTP 402 with the header `x-superbot-error: insufficient_balance`. The body is in the dialect of the route you called. Its `error.message` is two lines: a sentence that says what to do (for a credit-out, the billing page to add credits), then the status, code and billing reason in parentheses. OpenAI routes (`/v1/chat/completions`, `/v1/responses`): ```json { "error": { "message": "Your Superbot account has no plan or credits left. Add credits at https://superbot.gg/account/billing\n(402 insufficient_balance · no_plan)", "type": "invalid_request_error", "param": null, "code": "insufficient_balance", "refusal_class": "credit_out", "source": "account" } } ``` Anthropic routes (`/v1/messages`): ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "Your Superbot account has no plan or credits left. Add credits at https://superbot.gg/account/billing\n(402 insufficient_balance · no_plan)", "code": "insufficient_balance", "refusal_class": "credit_out", "source": "account" } } ``` `error.code` is `insufficient_balance` for every refusal that comes from the account's credit or spend limits, so it is the one code to branch on. `error.refusal_class` says which refusal it is, and `error.source` is `account`: the refusal comes from your account. | refusal_class | Meaning | | ----------------- | -------------------------------------------------------------------------------------------------- | | credit_out | no plan or credits left; add credits on the billing page | | weekly_cap | the plan's weekly pace limit is reached; it clears on its own, and the message says when it resets | | recharge_pending | a top-up is processing; try again in a few seconds | | limit | a spend limit is reached; the message says which one and where to change it | | suspended | the account is suspended; contact support | `https://superbot.gg/account/billing` is the page to add credits. All the top-up, subscribe, recharge and manage links name this one page. The link is not signed and does not expire: you sign in on the web to use it, and a pack or plan button on that page opens Stripe Checkout directly. On `GET /v1/plans`, a paid plan's `subscribe_url` is the same page with `?plan=` and the plan id on it. A refusal that is not a credit-out keeps this body: only `error.message` and `error.refusal_class` change, and a weekly cap, a pending top-up and a suspension name no billing page in the message. Superbot's own apps, signed in as the account, get a richer body with plan and balance fields. The billing reason is one of these: | reason | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------ | | no_plan | the account is on the free plan and its balance is spent | | topup_only | the account holds packs only and its balance is spent | | allowance_exhausted | the plan's monthly allowance is spent | | auto_recharge_off | the balance is spent and auto-recharge is off | | recharge_cap_reached | the next auto-recharge would pass its monthly limit | | recharge_failed | the auto-recharge charge failed | | recharge_pending | an auto-recharge is in flight; retryable | | weekly_cap_reached | the plan's weekly pace limit is reached; it clears on its own | | suspended | the account is suspended | | limit: | a spend limit is reached; the text after limit: names which one, such as key: and a key id | Related: [Credits](https://superbot.gg/docs#credits), [Plans and packs](https://superbot.gg/docs#plans) ## Account and billing ### Credits superbot bills in credits: one credit is $0.001. Each token type is priced as a multiple of the input rate (on superbot: output counted at 5x, cache reads at 0.05x and cache writes at 1.25x). A vendor model called on credits, with none of your own accounts attached, costs its own list price. Models on your own subscriptions and keys spend no credits. Credits are held and charged by the billing service behind superbot: the balance, the plan and every charge are its records, and the app and the API show what it reports. Calls with your API key bill at the API and MCP rate. An MCP connector turn bills at the same rate. superbot and superbot-fast both bill it. Neither model is free. In the Superbot apps, superbot and superbot-fast both bill at 20% of the API and MCP rate. #### Read your balance `GET /v1/credits` returns the balance as `balance_credits`, with the pots in `credits`, and the plan and auto-recharge state. `balance_credits` is the credit any model can spend; a plan's house allowance, spendable only on superbot and superbot-fast, is listed apart as `credits.house` and as a `house` row of `grants`, which names those models. It needs the `billing:read` scope, which **Models** and **Read-only query** keys hold. `low` is true at a balance of zero or less, and `reason` appears with it. The route reads the balance from billing and holds none itself, so while billing cannot be reached it answers 503 `billing_unavailable` with a retry hint. ```bash curl https://api.superbot.gg/v1/credits \ -H "Authorization: Bearer sbc_…" ``` Related: [Models](https://superbot.gg/docs#api-models), [The API page](https://superbot.gg/api) ### Plans and packs - Free costs nothing and carries 10,000 beta credits a month, refilled on the 1st (UTC). Cloud computer · 5 h/mo. - Superbot Plus is $20 a month with 22,000 credits included for any model and 250M Superbot tokens a month at 3:1 input to output, or $200 a year. Cloud computer · 20 h/mo. - Pro is $100 a month with 120,000 credits included for any model and 1.5B Superbot tokens a month at 3:1 input to output, or $960 a year. Cloud computer · 100 h/mo. - Max is $200 a month with 270,000 credits included for any model and 4B Superbot tokens a month at 3:1 input to output, or $1,920 a year. Cloud computer · 300 h/mo. - Superbot Teams is $25 a seat a month billed yearly at $300 a seat a year, with 30,000 credits a seat a month for any model and 300M Superbot tokens a seat a month at 3:1 input to output, pooled across the team. Cloud computer · 20 h/mo a seat. Every paid plan also sells a yearly term at the yearly price, and a yearly plan still releases its allowance monthly. any account can start a 7-day Superbot Pro trial at checkout: it takes a card, charges nothing during the trial, gives a one-time 20,000-credit grant that expires when the trial ends, and cancels when it ends unless you continue; an account gets one trial ever. Past the allowance, Plus and Teams bill $1.00 per 1,000 credits, Pro $0.90 and Max $0.80. Free accounts call models up to the mid tier; a frontier model needs Plus or a higher plan. Limits count every agent running at once. A plan's scheduled runs are its automation runs, on a cron or an interval. Packs are one-time purchases: 5,000 credits for $5, 20,000 for $20, 100,000 for $100, 275,000 for $250, 600,000 for $500, 1,250,000 for $1,000. A pack's credits never expire, and a plan does not reprice the $5/$20/$100/$250/$500/$1,000 packs. Plans and packs are bought on the billing page. **Account > Billing** opens it, and so does the `topup_url` or `subscribe_url` of a 402 or of `GET /v1/credits`: each opens that same page, which asks you to sign in if you are not already. A pack or plan button on it opens Stripe Checkout directly. #### Auto-recharge Auto-recharge charges your card for more credits when the balance falls to a level you set. It is off until you turn it on, then $20 per charge, capped at $100 per calendar month. Declined charges count toward the monthly limit. `GET /v1/credits` reports its state as `auto_recharge`, and the `reason` of a 402 says when it is off, capped or failed. Related: [Usage and spend](https://superbot.gg/docs#usage) ### Which credits are spent first Superbot models (superbot and superbot-fast) spend in this order: beta credits, the house allowance, plan allowance, promo credits, auto-recharge credits, packs. Every other model skips the house allowance, which only Superbot models can spend. Beta credits refill on the 1st (UTC); the house and plan allowances reset at renewal; none of the three rolls over. Packs and auto-recharge credits never expire. ## Help ### Troubleshooting Fixes for what goes wrong after you install the Helper. If superbot seems down, check [status.superbot.gg](https://status.superbot.gg). #### My AI client does not show superbot Restart the client. If it still lists no superbot tool, add the server again with its recipe under Your AI clients. #### superbot: command not found Paste the activation line the installer printed at the end. In sh, bash and zsh it is `export PATH="$HOME/.superbot/bin:$PATH"`. #### The installer did not sign me in Run `superbot signin`. It opens your browser to sign in. #### My caller key is refused A 401 means the key is missing or malformed, and a 403 means it was revoked or does not allow that model. Mint a new key in [Keys and authentication](https://superbot.gg/docs#api-auth). Related: [Your AI clients](https://superbot.gg/docs#clients) ### Remote SSH projects A project on an SSH host keeps its files, terminal and agents on that box. Click + and pick **Connect to an SSH host**, then choose a host or type `user@host`. #### The chat shows a connection error - **SSH sign-in failed**: enter the password, or add your key to ssh-agent or pick one for this host. - **Host key rejected**: the box's host key differs from the one you accepted. Check the fingerprint, then retry. - **Box unreachable**: the box did not answer. Check that it is on and reachable from your computer. - **Box platform unsupported**: the box needs Linux with glibc 2.28 or newer, or macOS, on x64 or arm64. Alpine and other musl Linux do not work. - **Box has no internet**: the box cannot download the Helper. **Send from this computer** (Send from this Mac on a Mac) copies it over. - **Port forwarding blocked**: allow `AllowTcpForwarding` in `sshd_config` on the box, then retry. - **Login shell prints output**: stop the shell profile or login banner from printing on connect, then retry. - **Engine missing on box**: **Reinstall** puts the engine back. - **OpenSSH too old**: update OpenSSH on your computer to 8.7 or newer, then retry. ### Uninstall `superbot uninstall` deletes superbot and everything it left on your machine: the Helper, the desktop app and its data, superbot's own entries in your AI clients, and your local accounts, chats and keys. You sign in again after a reinstall. `superbot uninstall --dry-run` lists what would go and deletes nothing. A script with no terminal has to pass `--yes`. To remove one client by hand, run `claude mcp remove superbot` for Claude Code, or delete the `superbot` entry from that client's config file. Nothing else was installed. Related: [Your AI clients](https://superbot.gg/docs#clients) ### More ways to read this This documentation in the formats other tools read. - [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. - [clients](https://superbot.gg/clients): the per-client setup pages. - [api](https://superbot.gg/api): the full rate card and the request formats. - [for teams](https://superbot.gg/teams): teams, spend, custom builds and pricing. - [request a client](https://superbot.gg/request-harness): one that is not on the list yet.