Onboarding API

The onboarding API drives first-run setup for local-server bootstrap. It lets the client check whether setup is complete, retrieve available provider and style options, and submit initial local-server configuration. LAN, remote, and Eliza Cloud connections can bypass most of this because the selected server may already own provider routing and runtime state.

Cloud provisioning bypass

When the agent is running as a cloud-provisioned container, onboarding is bypassed automatically. The bypass activates only when both conditions are met:

1. ELIZA_CLOUD_PROVISIONED=1 is set
2. ELIZA_API_TOKEN is configured

When cloud provisioned, GET /api/onboarding/status returns { "complete": true } so the frontend skips the setup wizard and goes directly to chat. A container with only the cloud flag but no API token falls through to the normal onboarding flow.

Endpoints

GET /api/onboarding/status

Returns whether the initial setup has been completed. Onboarding is considered complete when a config file exists and the agents section is populated. For cloud-provisioned containers, this always returns { "complete": true }.

Response

{
  "complete": true
}

GET /api/onboarding/options

Returns the available options for local-server bootstrap — random name suggestions, style presets, AI provider choices, cloud provider options, model selections, and inventory/RPC provider options.

Response

{
  "names": ["Aurora", "Luna", "Nyx", "Selene", "Nova"],
  "styles": [
    {
      "catchphrase": "chaotic",
      "hint": "chaotic good",
      "bio": ["Chaotic and curious AI companion."],
      "system": "You are {{name}}.",
      "style": { "all": ["be concise"], "chat": ["friendly"], "post": ["playful"] },
      "adjectives": ["curious", "playful"],
      "postExamples": ["hello world"],
      "messageExamples": [[{ "user": "User", "content": { "text": "hello" } }]]
    }
  ],
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "envKey": "OPENAI_API_KEY",
      "pluginName": "@elizaos/plugin-openai",
      "keyPrefix": "sk-",
      "description": "OpenAI API"
    }
  ],
  "cloudProviders": [
    {
      "id": "elizacloud",
      "name": "Eliza Cloud",
      "description": "Managed cloud runtime"
    }
  ],
  "models": {
    "small": [
      {
        "id": "small-model",
        "name": "Small Model",
        "provider": "elizacloud",
        "description": "Fast"
      }
    ],
    "large": [
      {
        "id": "large-model",
        "name": "Large Model",
        "provider": "elizacloud",
        "description": "High quality"
      }
    ]
  },
  "sharedStyleRules": ""
}

POST /api/onboarding

Submit the initial agent configuration. The onboarding API persists the selected runtime in the canonical config fields:

• deploymentTarget — where the active server runs (local, cloud, remote)
• linkedAccounts — which accounts are linked and available
• serviceRouting — which backend handles each capability (llmText, tts, media, embeddings, rpc)

The agent's name, bio, and systemPrompt are still persisted directly onto the active agent entry so the runtime retains its identity after restart.

Legacy onboarding request fields such as connection, runMode, cloudProvider, provider, providerApiKey, primaryModel, smallModel, and largeModel are rejected. Callers must send canonical deploymentTarget, linkedAccounts, serviceRouting, and credentialInputs instead.

Request Body

Example: Eliza Cloud hosting with direct Anthropic inference

{
  "name": "Eliza",
  "bio": ["A helpful AI assistant"],
  "deploymentTarget": {
    "runtime": "cloud",
    "provider": "elizacloud"
  },
  "linkedAccounts": {
    "elizacloud": {
      "status": "linked",
      "source": "oauth"
    }
  },
  "credentialInputs": {
    "cloudApiKey": "ck_live_example",
    "llmApiKey": "sk-ant-example"
  },
  "serviceRouting": {
    "llmText": {
      "backend": "anthropic",
      "transport": "direct",
      "primaryModel": "anthropic/claude-sonnet-4.6"
    }
  }
}

In this example, the agent is hosted on Eliza Cloud, but text inference still routes directly to Anthropic. Hosting, linked accounts, active service routing, and onboarding credential persistence are separate concerns.

Response

{
  "ok": true
}

Error Responses

Related: in-app wizard (frontend)

The HTTP API above backs server configuration. The chooser-first React onboarding flow (startup entry, step order, back/next, sidebar) is documented separately because it uses client-side flow helpers and must stay aligned with UI navigation without duplicating step lists. See Onboarding UI flow.