wololo
Get access

Provision Flow API

The provision flow creates a tenant record and triggers fleet provisioning. This is the sequence that runs when the onboarding wizard's Deploy step fires — it creates the tenant in Supabase, queues provisioning, and returns the tenant record. From there, provisioning runs asynchronously and the Fleet API reflects status as steps complete.

POST /api/tenants

Creates a new tenant and starts the provisioning pipeline. Admin-only — requires M2M platform auth. Called by the onboarding wizard; not intended for direct use by fleet users.

Request

POST /api/tenants
X-Platform-Token: <token>
Content-Type: application/json

{
  "tenantId":   "tenant_acme_01",
  "name":       "Acme Fleet",
  "plan":       "pro",
  "clerkOrgId": "org_abc123",
  "templateId": "standard-7-agent"
}

Fields

FieldRequiredDescription
tenantIdYesUnique tenant identifier. Snake-case, globally unique.
nameYesHuman-readable tenant name shown in dashboard.
planNoBilling plan. Defaults to free.
clerkOrgIdNoClerk organisation ID for org-scoped access. Omit for personal tenants.
templateIdNoFleet template to provision. Defaults to standard-7-agent.

Response — 200

{
  "ok": true,
  "tenant": {
    "tenant_id": "tenant_acme_01",
    "name": "Acme Fleet",
    "plan": "pro",
    "status": "pending",
    "template_id": "standard-7-agent",
    "clerk_org_id": "org_abc123",
    "repos": [],
    "agent_specs": [],
    "created_at": "2026-03-18T09:00:00.000Z",
    "updated_at": "2026-03-18T09:00:00.000Z"
  }
}

GET /api/tenants

Lists tenants. Admin-only. Supports filtering by status, plan, andclerkOrgId. Used by the platform admin dashboard — not exposed to fleet users.

Provisioning pipeline

After the tenant record is created with status: "pending", the provisioning pipeline picks it up and executes these steps in order:

  1. vm_create — spin up GCP VM in the target zone (e2-standard-2, europe-west2-b)
  2. workspace_bootstrap — create agent workspace directories, clone repos, install dependencies
  3. agent_config — write AGENTS.md, SOUL.md, IDENTITY.md, and workspace files for each agent from the template
  4. gateway_start — start the OpenClaw gateway process, verify it's listening
  5. connectivity_check — verify Discord channel connections and Mission Control reachability
  6. complete — update tenant status to active, write dashboardUrl

Each step writes to the provisioning_log table with status, message, and duration. Poll GET /api/fleet to watch progress in real time — the onboarding wizard streams this.

Error handling

If any provisioning step fails, the tenant status moves to errorand the failing step appears in the provisioning log withstatus: "failed" and an error message. Provisioning does not automatically retry — a failed provision requires manual intervention or re-running the wizard.

See also