Skip to content

clawd-runtime-services.mdx

Latest commit

 

History

History
59 lines (42 loc) · 3.43 KB

clawd-runtime-services.mdx

File metadata and controls

59 lines (42 loc) · 3.43 KB
Raw
title Clawd Runtime Services
description How Clawd uses Rigbox's AI proxy, credits, and configuration APIs.

This page documents how Clawd 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 (PUT /workspaces/{id}/mode) Sets managed/BYOK mode for each bot workspace (provider/model are account defaults) Managed Proxy, BYOK
Managed AI Proxy Routes AI SDK calls through Rigbox's proxy so bot workspaces don't need API keys Managed Proxy
Credits (GET /users/me/credits) Displays credit balance in the Clawd dashboard Resource Limits
AI Usage (GET /users/me/ai-usage) Shows per-day, per-workspace usage breakdown Managed Proxy
AI Defaults (PUT /users/me/ai-defaults) Lets users set default provider/model for new bot workspaces 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
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.

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: