> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chowder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Instance

> Spin up a new OpenClaw instance with a cloud sandbox.

Create a new instance. This kicks off a provisioning process that spins up a cloud sandbox, installs OpenClaw, configures your model provider, and starts the gateway. The endpoint returns immediately with `status: "provisioning"` — the sandbox takes roughly **\~90 seconds** to become fully ready.

Poll [Get Instance Status](/api-reference/instances/status) to know when provisioning completes.

<Note>
  Requires an **organization key** (`chd_org_*`). Your org must have an API key configured for the chosen `model_provider` — set one via [Update Organization](/api-reference/organization/update) first.
</Note>

## Request Body

<ParamField body="name" type="string" required>
  A name for the instance. 1–128 characters.
</ParamField>

<ParamField body="model_provider" type="string" default="anthropic">
  Which LLM provider to use. Your org must have an API key set for this provider.

  Options: `"anthropic"`, `"openai"`, `"gemini"`
</ParamField>

<ParamField body="sandbox_provider" type="string" default="sandbox">
  The cloud sandbox provider. Currently only `"sandbox"` is supported.
</ParamField>

<ParamField body="openclaw_version" type="string" default="v1">
  Which OpenClaw version to deploy. Defaults to `"v1"`.
</ParamField>

<ParamField body="openclaw_config" type="object">
  Optional config overrides passed to the OpenClaw instance. These are dot-path key/value pairs that get applied via `openclaw config set`. Useful for tweaking behavior, setting system prompts, etc.
</ParamField>

<ParamField body="region" type="string">
  Preferred region for the sandbox. If not specified, the default region is used.
</ParamField>

## Response

Returns `201 Created` with the instance object.

<ResponseField name="id" type="string">Unique instance ID (UUID).</ResponseField>
<ResponseField name="organization_id" type="string">The owning organization's ID.</ResponseField>
<ResponseField name="name" type="string">Instance name.</ResponseField>

<ResponseField name="status" type="string">
  Current status. Will be `"provisioning"` immediately after creation. See the [overview](/api-reference/overview#instance-lifecycle) for all possible states.
</ResponseField>

<ResponseField name="model_provider" type="string">The configured model provider.</ResponseField>
<ResponseField name="sandbox_provider" type="string">The sandbox provider (e.g. `"sandbox"`).</ResponseField>
<ResponseField name="sandbox_id" type="string | null">The underlying sandbox ID. `null` until provisioning completes.</ResponseField>
<ResponseField name="gateway_url" type="string | null">Public URL for the OpenClaw gateway. `null` until provisioning completes.</ResponseField>
<ResponseField name="openclaw_version" type="string">The deployed OpenClaw version.</ResponseField>
<ResponseField name="openclaw_config" type="object | null">Any config overrides applied to this instance.</ResponseField>
<ResponseField name="region" type="string | null">The sandbox region, if specified.</ResponseField>
<ResponseField name="error_message" type="string | null">If status is `"error"`, this explains what went wrong.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X POST https://api.chowder.dev/v1/instances \
    -H "Authorization: Bearer chd_org_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "my-assistant",
      "model_provider": "anthropic"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "my-assistant",
    "status": "provisioning",
    "model_provider": "anthropic",
    "sandbox_provider": "sandbox",
    "sandbox_id": null,
    "gateway_url": null,
    "openclaw_version": "v1",
    "openclaw_config": null,
    "region": null,
    "error_message": null,
    "created_at": "2026-02-14T16:00:00.000000+00:00",
    "updated_at": "2026-02-14T16:00:00.000000+00:00"
  }
  ```
</ResponseExample>