> ## 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.

# Sessions

> How chat sessions work in Chowder — default sessions, named sessions, and why isolation matters.

# 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`):

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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.

<Tip>
  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.
</Tip>

## 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

<Note>
  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.
</Note>

## Use cases

<CardGroup cols={2}>
  <Card title="Per-user conversations" icon="users">
    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.
  </Card>

  <Card title="Project threads" icon="folder">
    Different projects, different contexts. The agent in `project-atlas` knows about Atlas. The agent in `project-beacon` knows about Beacon.
  </Card>

  <Card title="Different personas" icon="masks-theater">
    Same instance, different system prompts per session. Use the `instructions` field in the request body to give each session its own personality.
  </Card>

  <Card title="Testing and staging" icon="flask">
    Run test conversations in a `test` session without polluting your production `main` session.
  </Card>
</CardGroup>

## 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:

| Endpoint                                                 | Session used     |
| -------------------------------------------------------- | ---------------- |
| `POST /v1/instances/{id}/responses`                      | `main` (default) |
| `POST /v1/instances/{id}/session/{session_id}/responses` | `{session_id}`   |

<Accordion title="Is there a limit on how many sessions I can have?">
  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.
</Accordion>

<Accordion title="Can I list or delete sessions?">
  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.
</Accordion>

<Accordion title="Do channel messages use sessions?">
  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.
</Accordion>