# Concepts

> The ideas behind Uncage, one section each: website and hub, machine and agent, session, run, events, approvals and permission modes, site tools, skills, manifest, file channel, storage, cluster, and the trust model.

<!-- https://uncage.vercel.app/docs/concepts/ -->

This page explains each idea once. The words are used the same way everywhere on this site; the [glossary](https://uncage.vercel.app/docs/reference/glossary.md) has the one-line versions.

## Website and hub

The **website** is your web application. The **hub** (`@uncage/hub`) is the part of Uncage you mount inside its backend with `createHub()`: in a long-running Node process (**traditional mode**) or in serverless functions (**FaaS mode**, see [Choose a deployment mode](https://uncage.vercel.app/docs/start/choose-deployment-mode.md)). It is a Fetch handler (`hub.fetch`) and serves, under one base path (default `/api/uncage`):

- the **browser API** your UI uses (the same request and response shapes as the Local Mode daemon’s `/v1` API, so `@uncage/client`, `@uncage/react` and `@uncage/react-ui` work unchanged);
- the **device endpoints** and the installers (`install.sh`, `install.ps1`) that connect a computer;
- the **transports** connected computers dial into at `<basePath>/agent`: a **WebSocket** (traditional mode, via `attachWebSocket(hub, server)` from `@uncage/hub/node`) and **HTTP streaming** (any platform). The hub offers them, the agent picks one.

Each website runs its own hub. There is no Uncage cloud service in between.

A website has an **id** and a **name** that computers see when they connect. By default both come from the host of `publicUrl` (`app.example.com`); set `site: { id, name }` to choose them. Computers use the id for their local folders, so keep it stable.

## Machine (computer) and agent

A **machine** is one user’s computer connected to your website. In UI text it is called a **computer**. A user can connect several; each one has an id (`mch_…`), a name, its OS, the agent version, the runtimes it has (Claude Code, Codex) and whether it is **online**.

The **agent** is the background process on that computer: `uncage agent`, installed by `uncage setup` as a per-user background service (launchd on macOS, systemd on Linux, a scheduled task on Windows). In Chinese UI text it is called **守护进程**. One agent can be connected to several websites at once, with one machine token, one connection and one workspace root per website.

A machine is **online** while its connection is live: a WebSocket answering heartbeats, or an open HTTP stream. The hub pings every 10 seconds and marks a silent machine offline after two missed pings, so the UI shows “offline” within about 30 seconds.

**Pairing** uses a device login, much like signing in to a TV app: `uncage setup <url>` gets a short **user code**, the user approves it on your website’s `/device` page, and the CLI receives a **machine token**. The token is stored only on the computer (`~/.uncage/agent.yaml`, mode 0600); the hub keeps its SHA-256 hash. Revoking a machine (from your website, or with `uncage sites remove` on the computer) makes the token stop working at once.

## Session

A **session** is one conversation, with one runtime, on one machine. Its id is chosen by the machine. Every session the hub returns carries `machineId`, so your UI can show the state of that computer.

- On the machine, each session gets its own **workspace** folder, `~/Uncage/<site host>/<session id>/`. A browser cannot choose the folder.
- The session’s **source of truth** is the machine’s local database (`~/.uncage/sites/<site id>/data`).
- A new session runs on the computer you pass as `machineId`, else on the user’s most recently seen computer that is online. With none online, creating a session fails with `machine_offline` (or `machine_not_found` if the user has never connected one).

## Run

A **run** is one prompt and everything the agent does to answer it. A session has at most one active run at a time (a second one gets `session_busy`). Run states:

| State | Meaning |
| --- | --- |
| `queued`, `running` | Working |
| `waiting_approval` | Paused on an approval card |
| `completed` | Finished normally |
| `failed` | Ended with an error |
| `cancelled` | Stopped by the user (Stop) |
| `interrupted` | The process went away mid-run (for example the agent restarted) |

Starting a run needs an `Idempotency-Key` header, so a retried request never starts a second run. `@uncage/client` sets it for you.

## Events

Everything that happens in a session is an **event** with a per-session **sequence** number: `session.created`, `run.started`, `message.delta`, `tool.started`, `approval.requested`, `run.completed`, and so on. The browser receives them over **SSE** (`GET <basePath>/sessions/:id/events`) and can resume after a disconnect from the last sequence it saw (`Last-Event-ID`). The machine writes events to its local database first, so a run keeps going while the network is down; when the connection comes back, the browser catches up without duplicates.

## Approvals and permission modes

When Claude Code wants to run a command, edit a file or call a tool that needs confirmation, the run pauses and the UI shows an **approval** card (**Allow** / **Deny**). The decision travels browser → hub → machine, and the machine decides atomically: if two tabs (or two hub nodes) answer at once, the first decision wins and the other gets `409`. Pending approvals expire after 10 minutes.

The **permission mode** of a session controls how much needs approval:

| Mode | Behaviour |
| --- | --- |
| `default` | Ask before commands and edits (Claude Code still auto-allows what it considers safe, such as reads) |
| `acceptEdits` | Edit files without asking; still ask for commands |
| `plan` | Plan only, change nothing |
| `auto` | The runtime decides what needs the user |
| `bypassPermissions` | Never ask. **Only available if the user enabled it on their own computer** (see [trust model](https://uncage.vercel.app/docs/concepts/trust-model.md)) |

## Site tools

A **site tool** is a capability of your website that Claude Code can call, declared with `defineTool({ name, description, input, handler, requiresConfirmation? })`.

- The machine receives only the name, the description and the JSON Schema of `input`. Claude Code sees the tool as `mcp__site__<name>`.
- The **handler runs in your backend**, on the hub node that holds the machine’s connection, with `ctx.user` set to the session’s owner.
- `requiresConfirmation: true` makes every call show an approval card first, even in `bypassPermissions` mode.
- Every call is checked (the session belongs to this machine and user, the tool was offered to this run, the arguments match `input`) and recorded in the hub’s store.

Guide: [Define tools](https://uncage.vercel.app/docs/guides/define-tools.md).

## Skills

A **skill** is instructions (markdown) plus optional template files, declared as a `SkillSpec` (`{ name, description, markdown, files? }`). The agent writes it to `.claude/skills/<name>/SKILL.md` in the session workspace before the run, and Claude Code loads it like any Claude Code skill: when the task matches its description. Skills are data, never code that the hub runs.

Guide: [Write skills](https://uncage.vercel.app/docs/guides/write-skills.md).

## Manifest

The **manifest** is the set of tools and skills offered to one run. By default it is every tool and skill you registered. With `selectManifest({ user, prompt, sessionId, runtime })` you choose per run, for example only offering the publishing tools to users on a paid plan, or only the `invoice` skill when the prompt is about invoices. The hub records each run’s tool list; a call to a tool outside it fails with `tool_failed` (`details.reason: 'not_in_manifest'`). Changes to your tools or skills apply from the next run. Runtimes without site tool support (Codex) get the skills only, with a `site_tools_unsupported` warning in the session.

Guide: [Choose tools and skills per run](https://uncage.vercel.app/docs/guides/select-manifest.md).

## File channel

The **file channel** lets a tool handler read files from the run’s workspace on the machine, instead of passing whole files through JSON arguments: `ctx.files.pull(path)` (a file or a folder, at most 50 MiB in total and 10 MiB per file) and `ctx.files.read(path)` (one file). The machine refuses paths outside the workspace, never follows symlinks, and skips hard-linked files in folders.

Guide: [Define tools → Reading files](https://uncage.vercel.app/docs/guides/define-tools.md#reading-files-from-the-users-computer).

## Storage

There are two stores:

- **On the machine:** the session data (truth), in PGlite under `~/.uncage/sites/<site id>/`.
- **On the hub (`HubStore`):** machines, device codes, the session index (who owns which session, on which machine), run manifests, attachments uploaded through the hub and the tool-call audit. In FaaS mode it also holds each machine’s **outbox** (the numbered commands it has not processed yet) and the tool-call results. `pgliteHubStore` (embedded, one process, from `@uncage/hub/node`) is for traditional mode; `postgresHubStore` is for several nodes and FaaS mode. You always pass one as `store`.

**Session storage** (`sessionStorage` option) decides whether the hub also keeps the conversation:

- `'machine'` (default): history is read from the machine. While it is offline, the user cannot see past conversations.
- `'site'`: the machine replicates every event to the hub, in order, and resends from the last acknowledged sequence after a reconnect. History stays readable on your site while the machine is off.

Guide: [Site storage](https://uncage.vercel.app/docs/guides/site-storage.md).

## Cluster

A hub can run on several **nodes** behind a load balancer; in FaaS mode every function instance is a node. A machine’s WebSocket lives on one node; a browser request may land on another. The **cluster adapter** (`ClusterAdapter`) shares which node holds which machine and carries commands, wake-ups and events between nodes. `memoryCluster()` (default) is for one process; `redisCluster()` or `postgresCluster()` is for several. Every node must also share one `HubStore` (Postgres).

Guide: [Multi-node](https://uncage.vercel.app/docs/guides/multi-node.md).

## Local policy and activity

The user’s computer has the last word. In `~/.uncage/agent.yaml`, `localPolicy.allowBypass` (default `false`) is the only switch that makes `bypassPermissions` possible, and `localPolicy.allowedPermissionModes` can cap the modes any website may use. Every command, tool call, file pull and approval a website causes is written to a local **activity log**, shown by `uncage activity`.

Guide: [Local policy](https://uncage.vercel.app/docs/guides/local-policy.md).

## Trust model

The website is trusted to act for its signed-in users, within limits the website cannot change: no code or shell from the website, bypass only by the user, a local log of everything. Read [the trust model](https://uncage.vercel.app/docs/concepts/trust-model.md).

## Local Mode

Everything above is **Connected Mode**. In **Local Mode**, there is no hub and no pairing: `uncage serve` (the **daemon**) runs on the same machine as your app, and your app talks to it through a same-origin **proxy** (`createUncageHandler` from `@uncage/server/proxy`) that adds the daemon’s bearer token on the server. Sessions, runs, events and approvals work the same way. See the [Local Mode quickstart](https://uncage.vercel.app/docs/start/quickstart-local.md).
