Skip to content

Getting started

This guide walks through creating an account, obtaining an API key, launching your first deployment, and verifying that everything is healthy.

Prerequisites

  • A Google account (for dashboard sign-in), or willingness to use programmatic signup via CLI/API
  • A paid tier if you intend to deploy — the free tier can explore the dashboard but cannot provision gateways (see Account)
  • For chat channels: tokens from Discord, Slack, Telegram, or another supported provider (optional at launch; you can configure later)

Step 1 — Create an account

  1. Open www.clusterclaw.ai/login.
  2. Choose Continue with Google.
  3. On first sign-in, ClusterClaw creates a customer record with the free tier and issues a fresh API key (stored in an HttpOnly cookie for dashboard RPC calls).

To deploy, upgrade to a paid tier from Pricing or complete Stripe checkout from dashboard settings.

Option B: CLI signup

Install the claw CLI (built from clients/cli/ in the repository, or use your team's published binary):

1
claw signup --name mycompany --tier developer

On success, the CLI prints your API key (cc_ prefix) and saves it to ~/.clusterclaw/config.json.

Option C: API signup

AccountService.Signup is a public endpoint — no API key required:

1
2
3
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.AccountService/Signup' \
  -H 'Content-Type: application/json' \
  -d '{"name":"mycompany","tier":"developer","email":"you@example.com"}'

The response includes customer and apiKey. Store the key immediately; it is shown once and cannot be retrieved later.

Protect your API key

Anyone with your cc_* key can manage deployments and billing on your account. Treat it like a password.

Step 2 — Save your API key

Surface How the key is stored
Dashboard HttpOnly cc_api_key cookie after Google sign-in (rotated each login)
CLI ~/.clusterclaw/config.json via claw login --key cc_...
Automation Environment variable CLUSTERCLAW_API_KEY or --api-key flag

Verify the key works:

1
2
export CLUSTERCLAW_API_KEY='cc_your_key_here'
claw account

Or call AccountService.GetAccount with Authorization: Bearer cc_....

Step 3 — Explore the launch catalog (optional)

Before creating a deployment, fetch supported models and chat channels:

1
2
3
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.CatalogService/GetLaunchCatalog' \
  -H 'Content-Type: application/json' \
  -d '{}'

GetLaunchCatalog is public (no auth). Channel secrets are never returned — only field metadata and documentation links.

Step 4 — Create your first deployment

Dashboard

  1. Sign in and open Dashboard → Deployments → New.
  2. Choose a name (DNS-safe label), region (us-central1 default), model, and channels.
  3. Enable Public ingress if you want a hostname like my-bot.clusterclaw.ai.
  4. Submit. Provisioning typically takes a few minutes.

CLI

1
2
3
4
5
claw deploy create \
  --name prod \
  --region us-central1 \
  --inference-mode platform-managed \
  --target-class cloud_run

Common flags:

Flag Default Notes
--region us-central1 GCP region
--inference-mode platform-managed Or byok, self-hosted, external-hosted
--target-class cloud_run autopilot requires enterprise tier
--storage 20Gi Persistent volume size

API

1
2
3
4
5
6
7
8
9
curl -sS -X POST 'https://api.clusterclaw.ai/openclaw.v1.DeploymentService/CreateDeployment' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CLUSTERCLAW_API_KEY" \
  -d '{
    "name": "prod",
    "region": "us-central1",
    "inferenceMode": "INFERENCE_MODE_PLATFORM_MANAGED",
    "publicIngressEnabled": true
  }'

Save the returned deployment.id — you need it for status, logs, and updates.

Step 5 — Wait for healthy status

Deployments move through provisioning states before reaching HEALTHY:

Status Meaning
QUEUED Accepted; waiting for provisioner
PROVISIONING / PROVISIONING_SERVICE Cloud resources being created
DNS_PENDING / TLS_PENDING Public hostname being wired (if enabled)
HEALTHY Gateway is running
FAILED Provisioning error — check logs and support

Poll status:

1
claw deploy status <deployment-id>

Or DeploymentService.GetDeploymentStatus / GetDeployment.

When status is HEALTHY and public ingress is enabled, open the gateway Control UI from the dashboard (Open gateway) or call GetDeploymentGatewayCredentials (returns a one-time SSO token — handle securely).

Step 6 — Health checks

Verify the control plane is reachable:

1
2
curl -sS 'https://api.clusterclaw.ai/healthz'
# ok

Verify your deployment gateway (after HEALTHY):

1
curl -sS -o /dev/null -w '%{http_code}\n' 'https://my-bot.clusterclaw.ai/'

A 200 or redirect to the Control UI indicates the public route is live. Exact response depends on gateway auth settings.

Step 7 — Connect a chat channel (optional)

Guided channels (Discord, Slack, Telegram) can be configured at launch via the dashboard form or seedOverridesJson / catalog field keys in the API.

For Slack, hosted deployments use Socket Mode — no public webhook URL required. See Deployments → Connect Slack.

After the gateway is healthy, approve DM pairing when using the default pairing policy:

1
openclaw pairing approve slack <code>

(Run from a context with access to your gateway, or use the Control UI.)

Next steps