Skip to main content

​
Instances

An instance is a running OpenClaw agent. It’s the core unit of everything in Chowder. When you create an instance, Chowder spins up an isolated cloud sandbox, installs OpenClaw, starts the gateway, and hands you back a running agent you can talk to, connect channels to, and extend with skills. Each instance gets its own:
  • Sandbox — a cloud container with its own filesystem
  • Gateway — an HTTP server that handles requests, sessions, and channel bridges
  • Workspace — a persistent directory for files, skills, and configuration
  • Memory — conversation history and context, scoped per session
Think of an instance as a self-contained AI agent living in its own little world.

​
Instance lifecycle

Every instance moves through a predictable set of states:
1

Provisioning

You call POST /v1/instances and Chowder immediately returns a row with status: "provisioning". In the background, it’s creating a sandbox, running OpenClaw’s onboard process, configuring the gateway, and starting it up.This takes about 60–90 seconds. You can poll GET /v1/instances/{id} until the status flips to running.
2

Running

The instance is live. You can send it messages, connect channels, install skills, and manage files. The gateway is accepting requests and the sandbox is awake.
3

Stopped

You called POST /v1/instances/{id}/stop. The sandbox is hibernated — it’s still there, but not consuming compute. The gateway is down. No messages can be sent.Starting it back up is much faster than the initial provision (~10–15 seconds).
4

Terminated

You called DELETE /v1/instances/{id}. The sandbox is destroyed, the data is gone, and the instance won’t show up in list calls. This is permanent.
If provisioning fails (bad API key, sandbox issue, etc.), the instance enters an error state with an error_message field explaining what went wrong. You can delete it and try again.

​
What happens during provisioning

When you create an instance, here’s what Chowder does behind the scenes:
  1. Creates a sandbox from the sandbox-medium snapshot (OpenClaw comes pre-installed)
  2. Runs openclaw onboard with your model provider credentials to write the initial config
  3. Generates a gateway auth token and configures token-based gateway authentication
  4. Enables the responses endpoint so the API can proxy messages to your agent
  5. Applies any custom config you passed in openclaw_config
  6. Starts the gateway in the background
  7. Resolves the public URL and persists everything to the database
All of this happens asynchronously — the create call returns immediately so you’re not blocked waiting.

​
Model providers

Each instance is backed by a language model. You choose the provider when creating the instance: 
curl -X POST https://api.chowder.dev/v1/instances \
  -H "Authorization: Bearer $CHOWDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "model_provider": "anthropic"
  }'
Uses your Anthropic API key. Models like Claude Sonnet, Claude Opus, etc.
You need to configure your model provider API key on your organization before creating an instance. Set it via PATCH /v1/organization — otherwise the create call will fail with a 400.

​
Instance limits

How many instances you can run depends on your subscription tier:
TierInstance limit
Shrimp (free)1
Crab10
Lobster500
Whale (enterprise)Unlimited
Limits are enforced at creation time. If you’re at capacity, the API returns a 402 with a message telling you to upgrade. See Subscriptions & Billing for details.

​
Starting and stopping

Stopped instances aren’t gone — they’re hibernated. The sandbox still exists, all your files and config are preserved, and you can bring it back online whenever you want. 
# Stop an instance (sandbox hibernates)
curl -X POST https://api.chowder.dev/v1/instances/{id}/stop \
  -H "Authorization: Bearer $CHOWDER_KEY"

# Start it back up (~10-15 seconds)
curl -X POST https://api.chowder.dev/v1/instances/{id}/start \
  -H "Authorization: Bearer $CHOWDER_KEY"
This is useful for:
  • Cost management — stopped instances don’t consume compute
  • Development workflows — spin up for testing, stop when you’re done
  • Scheduled agents — start at 9am, stop at 5pm
Starting a stopped instance is significantly faster than provisioning a new one, because the sandbox already exists and OpenClaw is already installed. The gateway just needs to boot.
Not directly. The model provider is set during onboard and baked into the gateway config. If you need a different provider, create a new instance. You can use the files API to migrate workspace data between instances if needed.
Channel connections are preserved in the config, but they go offline when the gateway stops. When you start the instance again, channels will automatically reconnect (assuming your tokens are still valid).