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

# Architecture

> How chats, the Computer Use Server, and per-session Docker sandboxes fit together.

## Big picture

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/architecture.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=4e324b684a5261fe0874c9ba77f98a6f" alt="Open Computer Use architecture" width="900" height="520" data-path="images/diagrams/architecture.svg" />
</Frame>

Three moving parts:

1. **MCP client** — Open WebUI, Claude Desktop, LiteLLM, n8n, or anything that speaks MCP over Streamable HTTP.
2. **Computer Use Server** (the orchestrator) — stateless HTTP service that routes MCP requests to per-chat sandbox containers, serves the system prompt, exposes the live browser/terminal, and hosts file previews.
3. **Sandbox container** — one Docker container per `X-Chat-Id`. Full Ubuntu userspace with the tools listed in [Introduction](/introduction#whats-inside-the-sandbox).

## Data flow

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/data-flow.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=e28314d94b12746403ea719f480e23d7" alt="Data flow from chat to sandbox" width="500" height="520" data-path="images/diagrams/data-flow.svg" />
</Frame>

Each MCP request carries `X-Chat-Id` (mandatory in strict multi-user mode). The orchestrator creates the sandbox lazily on first use and tears it down after `CONTAINER_MAX_AGE_HOURS`. Everything is isolated — the AI can install packages, create files, run servers, and nothing leaks between users.

## Sandbox contents

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/sandbox-contents.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=6b97a19427015332be94351ff3d4b913" alt="What's inside each sandbox container" width="900" height="820" data-path="images/diagrams/sandbox-contents.svg" />
</Frame>

## The live browser

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/shared-browser.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=5683da7d1bbe7f3e92f7a964d515b010" alt="Shared CDP browser between the model and the user" width="920" height="520" data-path="images/diagrams/shared-browser.svg" />
</Frame>

Each sandbox runs Chromium with the Chrome DevTools Protocol exposed. The orchestrator bridges CDP over WebSocket, so the user sees exactly what the model is doing — and can click through if needed. See [Live browser](/features/browser).

## The terminal tab

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/terminal-flow.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=4b48136624acd9e1496c4183236aa673" alt="ttyd + tmux + Claude Code CLI in the terminal tab" width="820" height="200" data-path="images/diagrams/terminal-flow.svg" />
</Frame>

Open WebUI gets a dedicated terminal tab backed by `ttyd + tmux`. The sub-agent tool launches Claude Code CLI inside a named tmux session — you can attach, watch, or take over. See [Terminal](/features/terminal).

## File pipeline

<Frame>
  <img src="https://mintcdn.com/yambr/AQ23_2YQrfJDjXh_/images/diagrams/file-flow.svg?fit=max&auto=format&n=AQ23_2YQrfJDjXh_&q=85&s=e1c04b8615758093145c99e25bcf58fc" alt="File upload, sandbox, preview pipeline" width="920" height="480" data-path="images/diagrams/file-flow.svg" />
</Frame>

Uploads land on the orchestrator, get mounted into `/home/assistant/uploads/{chat_id}/` inside the sandbox, and are re-exposed as MCP `resources/list` entries. Files the model creates are served back through the same public endpoint (`cu.yambr.com/files/...` in managed Yambr; `http://localhost:8081/files/...` self-hosted) and auto-previewed in Open WebUI's artifacts panel. See [File preview](/features/file-preview).

## The system prompt — six redundant channels

The per-chat system prompt isn't just pasted into a single field. It's delivered through **six MCP-native and HTTP channels** so the model can recover its environment even if a client strips one of them:

1. Tool descriptions (every MCP tool includes context)
2. `/home/assistant/README.md` inside the sandbox (readable by the `view` tool)
3. `InitializeResult.instructions` (MCP handshake)
4. `resources/list` + `resources/read` (uploaded files)
5. HTTP `GET /system-prompt` (legacy integrations)
6. HTTP `GET /skill-list` (for sub-agent delegation)

Full map: [System prompt reference](/reference/system-prompt).

## Session isolation

Controlled by `SINGLE_USER_MODE`:

| Mode    | `X-Chat-Id` | Behavior                                                    |
| ------- | ----------- | ----------------------------------------------------------- |
| *unset* | Yes         | Isolated container per chat ID                              |
| *unset* | No          | Shared `default` container + warning in every tool response |
| `true`  | *any*       | Always one `default` container; header ignored              |
| `false` | Yes         | Strict: isolated container per chat ID                      |
| `false` | No          | **Rejected** with error                                     |

Managed Yambr runs strict multi-user mode. See [MCP API reference](/api-reference/introduction) for header details.