Skip to main content

​
Quickstart

This guide walks you through creating a workspace, starting it, reconciling template apps, and validating live routing.

​
Prerequisites

  • A Rigbox account (sign up here)
  • An API key (get one from Settings → API Keys in the dashboard)
  • jq installed locally for parsing JSON in shell examples

​
Step 1: Quick Deploy an OpenClaw Workspace

Quick Deploy creates a workspace with template defaults. For OpenClaw, this provisions an openclaw image workspace. 
curl -X POST https://api.rigbox.dev/api/quick-deploy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "openclaw",
    "name": "my-bot"
  }'
Example response: 
{
  "workspace": {
    "id": "ws-a1b2c3d4",
    "name": "my-bot",
    "image": "openclaw",
    "status": "provisioned",
    "ram_mb": 4096,
    "disk_size_mb": 10240,
    "vcpu_count": 2,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "message": "Workspace 'my-bot' created from template 'OpenClaw Bot'. Start it to begin working.",
  "installed_apps": [],
  "expected_apps": []
}

​
Step 2: Start the Workspace

WORKSPACE_ID="ws-a1b2c3d4"

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

​
Step 3: Poll Until Running

for i in {1..60}; do
  STATUS=$(curl -s "https://api.rigbox.dev/api/workspaces/${WORKSPACE_ID}" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.vm.status')

  echo "status=${STATUS}"
  if [ "${STATUS}" = "running" ]; then
    break
  fi

  sleep 2
done

​
Step 4: Reconcile Template Apps

Ensure expected template apps (for example OpenClaw gateway) exist: 
curl -X POST "https://api.rigbox.dev/api/workspaces/${WORKSPACE_ID}/reconcile-apps" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Step 5: List Apps and Validate Live Health

List apps: 
curl https://api.rigbox.dev/api/apps \
  -H "Authorization: Bearer YOUR_API_KEY"
Check a specific app is reachable before surfacing its URL in your own UI: 
APP_ID="app-x1y2z3"

curl "https://api.rigbox.dev/api/apps/${APP_ID}/health" \
  -H "Authorization: Bearer YOUR_API_KEY"
Expected response: 
{
  "live": true,
  "service_status": "running",
  "port_open": true
}

​
Optional: Configure AI Settings

For workspaces with AI integration, use the typed config endpoint: 
curl -X PUT "https://api.rigbox.dev/api/workspaces/${WORKSPACE_ID}/ai-config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "managed",
    "provider": "google",
    "model": "google/gemini-2.5-pro"
  }'
Use null on nullable fields (for example api_key) to explicitly clear values. Omitted fields keep their existing values.

​
Next Steps

Workspace API

Full workspace lifecycle management

App Management

Port exposure, visibility controls, and health checks

Snapshots

Save and restore workspace state

AI Configuration

Manage AI provider settings and credits

Tools

Install and manage workspace tools

Setup Scripts

Automate workspace initialization

API Keys

Manage programmatic access

Clawd API Surface

See the exact endpoint groups used by clawd.rigbox.dev