Trust model
View as MarkdownConnected Mode lets a website start work on a user’s own computer. That needs a clear answer to “what can the website do?”. Here it is.
The short version
Section titled “The short version”- The website is trusted to act for its signed-in user. What the user does on your website counts as the user’s own action: starting runs, approving cards, calling your tools as that user.
- Within limits the website cannot change. These are enforced on the user’s computer, by the agent, not by the hub:
| Guarantee | How |
|---|---|
| No code or shell from the website | The hub sends only data: tool names, descriptions and JSON Schemas, skill text and template files, and commands from a fixed list (create session, start run, cancel, decide, update settings, add attachment, read snapshot / sessions / events). Tool handlers run on your server, never on the user’s computer. |
bypassPermissions only by the user |
The agent refuses the mode with policy_denied unless localPolicy.allowBypass: true is set in ~/.uncage/agent.yaml on that computer. No hub option can change this. |
| Optional local cap | localPolicy.allowedPermissionModes limits which modes any website may use on this computer. |
| Confirmation tools always ask | A site tool with requiresConfirmation: true raises an approval card on every call, even in bypassPermissions mode. |
| A full local record | Every command, site tool call, file pull and approval is appended to ~/.uncage/sites/<site id>/activity.log. uncage activity shows it. |
| Fenced folders | Every session runs in its own folder, ~/Uncage/<site host>/<session id>/, never in the user’s existing projects. File pulls are refused outside it, and symlinks are never followed. |
| The user can disconnect at any time | uncage sites remove <id> revokes the computer on the website and deletes the token locally; uncage agent uninstall stops the agent. |
What the website can do
Section titled “What the website can do”- Start sessions and runs on the user’s connected computers, as that user, with the permission modes the computer allows.
- Show the user approval cards and receive the user’s decisions.
- Offer site tools and skills. Claude Code decides when to call a tool; the call runs your handler on your server.
- Read files from the session’s own folder through the file channel, from inside a tool handler.
- Keep a replica of the conversation on its own storage (
sessionStorage: 'site'). - Revoke a computer from its side (
hub.revokeMachineor the machine list in the UI).
What the website cannot do
Section titled “What the website cannot do”- Run anything on the user’s computer other than Claude Code (or Codex) itself, in a session folder.
- Turn on
bypassPermissions, or use a mode outside the computer’sallowedPermissionModes. - Choose where a session runs on disk. The browser’s
workspacefield is ignored in Connected Mode; the agent creates the folder. - Reach another user’s computer or session. Every browser request is checked against
getUser(req), and a session or machine of another user answers404, exactly like one that does not exist. - See the machine token. The hub stores only its hash; the token is never logged or put in events.
- Read the user’s Claude login. Claude Code uses its own credentials on that computer.
What the user should know
Section titled “What the user should know”These are the trade-offs the user accepts by connecting a computer:
- Claude Code acts within the session folder and its permission mode, with the user’s own account. In
defaultmode the user approves commands and edits. Claude Code itself auto-allows some actions it considers safe, such as reading files. Those still appear as tool steps. - A command the user approves runs with the user’s rights, like any Claude Code command. Approval cards show the command or path; read them.
- Approve only a computer you just connected yourself. Approving a code links that computer to the account: it then receives the account’s prompts, attachments and site-tool calls. Anyone can start
uncage setupagainst the website on their own computer and send a user the link, so the approve page warns, shows when and from which IP the code was requested, and asks for the code’s last 4 characters from the user’s own terminal before Approve works. Never approve a code someone sent you. - The website sees the conversation (it routes it, and may store it). It does not see other files on the computer unless Claude Code reads them into the conversation or a tool pulls them from the session folder.
For website developers: your side of the deal
Section titled “For website developers: your side of the deal”Uncage cannot protect against a website that misuses its own users’ trust, but it gives you the pieces to deserve it:
- Authenticate every request.
getUser(req)must return the real signed-in user ornull. See Auth and device approval. - Protect
/device. Approving a code links a computer to an account. Serve it only to the signed-in user, refuse framing, decide with a CSRF-protected POST, and never trust a code that arrived in the link: warn, show the request time and IP, and require the code’s last 4 characters (phishing links). - Check ownership in tool handlers.
ctx.useris the session owner; use it for every lookup (WHERE owner = ctx.user.id). - Throw user-safe errors. A handler’s thrown message is shown to the user and the model.
- Use
requiresConfirmationfor any tool that publishes, sends, pays or deletes.
See also Security for the transport, tokens and limits.