> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Clawd Runtime Services

> How Clawd uses Rigbox's AI proxy, credits, and configuration APIs.

This page documents how [Clawd](https://clawd.rigbox.dev) uses Rigbox's general-purpose AI and configuration APIs to power its bot hosting experience. These are not Clawd-specific APIs - they're available to any Rigbox integration.

## APIs used by Clawd's runtime

| API                                                                                             | How Clawd uses it                                                                   | Guide                                                        |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Workspace AI Mode](/api-reference/ai/update-workspace-ai-config) (`PUT /workspaces/{id}/mode`) | Sets managed/BYOK mode for each bot workspace (provider/model are account defaults) | [Managed Proxy](/guides/managed-proxy), [BYOK](/guides/byok) |
| [Managed AI Proxy](/guides/managed-proxy)                                                       | Routes AI SDK calls through Rigbox's proxy so bot workspaces don't need API keys    | [Managed Proxy](/guides/managed-proxy)                       |
| [Credits](/api-reference/ai/get-credits) (`GET /users/me/credits`)                              | Displays credit balance in the Clawd dashboard                                      | [Resource Limits](/concepts/limits)                          |
| [AI Usage](/api-reference/ai/get-usage) (`GET /users/me/ai-usage`)                              | Shows per-day, per-workspace usage breakdown                                        | [Managed Proxy](/guides/managed-proxy)                       |
| [AI Defaults](/api-reference/ai/update-defaults) (`PUT /users/me/ai-defaults`)                  | Lets users set default provider/model for new bot workspaces                        | [BYOK](/guides/byok)                                         |

## How the managed proxy powers Clawd bots

When a Clawd bot workspace is in managed mode:

1. The bot's code calls the AI SDK (e.g., Anthropic, OpenAI) using standard endpoints
2. The workspace's proxy configuration routes these calls through Rigbox's bridge-local AI proxy
3. The proxy injects the real provider API key - the bot workspace never sees it
4. Token usage is metered and deducted from the user's credit balance
5. If credits run out, requests return `402` and the Clawd UI prompts an upgrade

<Note>
  The managed AI proxy is a general Rigbox feature, not Clawd-specific. Any workspace can use it by setting `mode: "managed"` via the [Workspace AI Mode API](/api-reference/ai/update-workspace-ai-config), then running `eval "$(rig proxy on)"` or sourcing `~/.rigbox/proxy.env` inside the VM.
</Note>

## AI config fields

AI configuration is split across two endpoints. A workspace's mode is set with `PUT /workspaces/{id}/mode`:

| Field  | Type                             | Description                                                                          |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------ |
| `mode` | `"managed"`, `"byok"`, or `null` | Per-workspace mode; `null` clears the override and falls back to the account default |

Provider and model are account-level defaults, set with `PUT /users/me/ai-defaults`:

| Field              | Type                                  | Description                     |
| ------------------ | ------------------------------------- | ------------------------------- |
| `default_mode`     | `"managed"` or `"byok"`               | Default mode for new workspaces |
| `default_provider` | `"google"`, `"openai"`, `"anthropic"` | Default AI provider             |
| `default_model`    | `string` or `null`                    | Default model identifier        |

In BYOK mode, supply your provider key to the workspace as an environment variable (e.g. `ANTHROPIC_API_KEY`) via `POST /workspaces/{id}/env` — there is no `api_key` config field.

* Omitted fields keep their current value
* Set a field to `null` to clear it

## Building something similar

If you're building your own AI-powered hosting platform on Rigbox, the same APIs that power Clawd are available to you. See:

* [Build a Hosting Platform](/guides/build-hosting-platform) - end-to-end tutorial
* [Clawd API Surface](/clawd-api-surface) - full endpoint map of what Clawd calls
* [Managed AI Proxy](/guides/managed-proxy) - detailed proxy and credit guide