Skip to main content

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.

Rigbox provides the infrastructure primitives - isolated VMs, app routing, AI proxy, and credit management - so you can build a hosting platform on top without managing servers. This guide walks through building a service like Clawd (an AI bot hosting platform) using the Rigbox API. By the end, you will have a working architecture for provisioning user workspaces, exposing apps, and managing AI credits.

​
Architecture Overview

Your platform sits between your users and the Rigbox API: Each user gets their own isolated micro-VM. Your backend orchestrates lifecycle, configuration, and monitoring through the Rigbox API. You handle user auth and billing; Rigbox handles VM isolation, networking, and AI proxy.
You handle user authentication and billing. Rigbox handles VM isolation, networking, and the AI proxy. This separation lets you focus on your product while Rigbox manages the infrastructure.

​
Step 1: Provision a Workspace

When a user signs up on your platform, provision a workspace for them using the quick-deploy endpoint. This creates a workspace from a template with sensible defaults. 
curl -X POST https://api.rigbox.dev/api/v1/quick-deploy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-abc-workspace",
    "template": "ai-agent-starter"
  }'
Store the returned workspace_id in your database, linked to the user. This is how you will manage their workspace going forward. Available templates include:
TemplateUse case
ai-agent-starterAI agent with tool use and memory
openclawTelegram bot with AI backend
web-fullstackReact + Node.js starter
baseMinimal workspace, no extras
devFull development environment
Start with quick-deploy for the simplest provisioning flow. It creates the workspace, applies the template, and starts the VM in a single API call.

​
Step 2: Configure AI

Set up the AI configuration for the workspace. You can use Rigbox’s managed credits or let users bring their own keys (BYOK). Rigbox injects API keys and tracks usage against the user’s credit balance: 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "managed",
    "default_provider": "anthropic",
    "default_model": "claude-sonnet-4-20250514"
  }'

​
BYOK mode

Let users provide their own API keys: 
curl -X PUT https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/ai-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "byok",
    "provider_keys": {
      "openai": "sk-...",
      "anthropic": "sk-ant-..."
    }
  }'
In BYOK mode, API keys are stored securely in the control plane and injected into the VM at runtime. They are never exposed to the data plane or to other users.
Your UI can offer a settings page where users choose between managed and BYOK, and select their preferred provider and model.

​
Step 3: Expose the App

Once the workspace is running, you need to create app routes so your users’ services are accessible from the internet.

​
Reconcile template apps

If the workspace was created from a template, reconcile to create the default app routes: 
curl -X POST https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/reconcile-apps \
  -H "Authorization: Bearer YOUR_API_KEY"
This reads the template’s app definitions and creates routes for each one.

​
Create a custom app route

For custom services, create an app route manually: 
curl -X POST https://api.rigbox.dev/api/v1/apps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_abc123",
    "name": "user-api",
    "port": 3000,
    "subdomain": "user-abc-api"
  }'
Each app gets a unique subdomain: {subdomain}.rigbox.dev with automatic HTTPS.

​
Step 4: Control Access

Set the visibility of each app based on your platform’s requirements.

​
Make an app public

For user-facing apps that should be accessible by anyone: 
curl -X PUT https://api.rigbox.dev/api/v1/apps/{app_id}/visibility \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public"
  }'

​
Restrict to specific users

For team or internal apps, use privileged mode with an allowlist: 
curl -X PUT https://api.rigbox.dev/api/v1/apps/{app_id}/visibility \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "privileged",
    "allowed_emails": [
      "alice@example.com",
      "bob@example.com"
    ]
  }'
VisibilityAccess
privateOnly the workspace owner
privilegedOwner + allowed emails
publicAnyone with the URL

​
Step 5: Monitor Health

Check app health before showing a “live” status indicator in your UI. 
# App-level health check
curl https://api.rigbox.dev/api/v1/apps/{app_id}/health \
  -H "Authorization: Bearer YOUR_API_KEY"

# Workspace-level metrics (CPU, memory, disk)
curl https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"
The health endpoint returns a status field (healthy, degraded, or down) that you can map to a status badge in your UI. The metrics endpoint returns CPU, memory, and disk usage for resource dashboards.

​
Step 6: Show Credits and Usage

Display credit balance and AI usage in your dashboard. Three endpoints give you everything you need for a usage dashboard: 
# Credit balance
curl https://api.rigbox.dev/api/v1/users/me/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

# AI usage history
curl https://api.rigbox.dev/api/v1/users/me/ai-usage \
  -H "Authorization: Bearer YOUR_API_KEY"

# Plan limits (max workspaces, memory, monthly credits)
curl https://api.rigbox.dev/api/v1/users/me/limits \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Step 7: Lifecycle Management

Let users control their workspace instances through your UI.

​
Start a workspace

curl -X POST https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/start \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Stop a workspace

curl -X POST https://api.rigbox.dev/api/v1/workspaces/{workspace_id}/stop \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Delete a workspace

curl -X DELETE https://api.rigbox.dev/api/v1/workspaces/{workspace_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
Workspace deletion is permanent and cannot be undone. Show a confirmation dialog in your UI before calling this endpoint.

​
Real-World Examples

​
How Clawd does it

Clawd is an AI bot hosting platform built on Rigbox. Here is what makes it unique:
  • Template: Uses openclaw for Telegram bot deployment
  • Billing: Integrates Stripe for credit pack sales (billing is handled outside the Rigbox API)
  • Dashboard: Shows real-time metrics and AI credit balance
  • AI config: Lets users pick their provider and model through a settings UI
See the full API integration at Clawd API Surface.

​
How Sandbox does it

Sandbox is a general-purpose coding environment built on Rigbox:
  • Template: Uses base and dev templates for coding workspaces
  • Terminal: Integrates terminal access via xterm.js WebSocket connections
  • Logs: Streams app logs in real time via SSE (Server-Sent Events)
  • Apps: Lets users create and manage multiple app routes per workspace
See the full API integration at Sandbox API Surface.
Start by building the workspace provisioning flow with quick-deploy. Once that works, layer on app management, AI config, and monitoring incrementally.

​
Next Steps