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

# Sessions

> Route same user to same worker

## What Sessions Do

Sessions route requests with the same ID to the same worker.

```bash theme={null}
# Both hit the same worker
orpheus run agent '{}' --session user-123
orpheus run agent '{}' --session user-123
```

<img className="block" src="https://mintcdn.com/orpheussysteminc/hc-RHMSh1-Rpu87T/assets/sessions.svg?fit=max&auto=format&n=hc-RHMSh1-Rpu87T&q=85&s=be22d82550627ec00a053a833ad21bb5" alt="workers" width="19492" height="8691" data-path="assets/sessions.svg" />

***

## Why Use Sessions

Workers keep state in memory. Same worker = same state.

* Loaded models stay loaded
* Conversation context persists
* Caches remain warm

## How It Works

1. Request arrives with `session_id`
2. Orpheus checks which worker last handled that session
3. Routes to that worker (if available)
4. Falls back to any worker if busy

## Best-Effort

Sessions are best-effort, not guaranteed:

* If preferred worker is busy → another handles it
* If worker dies → new worker, fresh state

For guaranteed persistence, use workspace.

## When to Use

| Need                 | Solution             |
| -------------------- | -------------------- |
| Fast in-memory state | Sessions             |
| Durable state        | Workspace            |
| Both                 | Sessions + Workspace |