Skip to main content

​
Sessions

Sessions let you run multiple independent conversations with the same instance. Each session has its own memory, context, and conversation history — completely isolated from every other session. This is how you build things like per-user chat threads, project-specific assistants, or multi-persona agents on a single instance.

​
The default session

When you send a message to an instance without specifying a session, it goes to the default session (called main): 
# This uses the default session
curl -X POST https://api.chowder.dev/v1/instances/{id}/responses \
  -H "Authorization: Bearer $CHOWDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "input": "Hey, remember me?"}'
The default session is always there. You don’t need to create it. If you’re building something simple — a single chatbot, a personal assistant — this is all you need.

​
Named sessions

For anything more complex, use named sessions. Just include a session ID in the URL: 
# This creates (or continues) a session called "user-42"
curl -X POST https://api.chowder.dev/v1/instances/{id}/session/user-42/responses \
  -H "Authorization: Bearer $CHOWDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "input": "What were we talking about?"}'
Sessions are created on first use — there’s no explicit “create session” step. Just pick a session ID and start sending messages.
Session IDs can be any string. Use something meaningful: a user ID (user-42), a project name (project-atlas), a thread ID (thread-abc123), whatever maps to your use case.

​
Session isolation

This is the important part: sessions are completely isolated. A message in one session has zero visibility into what happened in another. 
Instance "my-agent"
├── main (default)     → "Help me write a haiku"
├── user-42            → "Debug my Python code"
├── user-88            → "Translate this to Spanish"
└── project-atlas      → "Summarize the Q4 report"
Each of these sessions:
  • Has its own conversation history — the agent doesn’t mix up who said what
  • Maintains its own context window — previous messages from other sessions don’t eat into the limit
  • Has its own memory — things the agent “remembers” are session-specific
Skills and workspace files are shared across sessions — they belong to the instance, not the session. If you install a browser skill, all sessions can use it. If you upload a file, all sessions can access it.

​
Use cases

Per-user conversations

Map each user in your app to a session. User A’s conversation is private from User B’s. One instance serves all your users.

Project threads

Different projects, different contexts. The agent in project-atlas knows about Atlas. The agent in project-beacon knows about Beacon.

Different personas

Same instance, different system prompts per session. Use the instructions field in the request body to give each session its own personality.

Testing and staging

Run test conversations in a test session without polluting your production main session.

​
How it works under the hood

You don’t need to know this to use sessions, but if you’re curious: Chowder proxies your request to the OpenClaw gateway running inside the instance’s sandbox. When you specify a session ID, Chowder includes it as an x-openclaw-session-key header on the proxied request. OpenClaw uses this to route the message to the right session context. You never need to set this header yourself — Chowder handles it based on the URL you call:
EndpointSession used
POST /v1/instances/{id}/responsesmain (default)
POST /v1/instances/{id}/session/{session_id}/responses{session_id}
There’s no hard limit from Chowder’s side. Sessions are managed by OpenClaw within the instance sandbox. In practice, you’re bounded by the sandbox’s memory — each active session maintains its own conversation state. For most use cases, you can comfortably run hundreds of sessions per instance.
Not through the Chowder API currently. Sessions are managed internally by OpenClaw. If you need to reset a session, you can send a message with fresh instructions, or create a new instance for a clean slate.
Yes. Each channel connection effectively operates in its own session context. When someone messages your agent on Telegram, it doesn’t interfere with a conversation happening on Discord or through the API.