Security
View as MarkdownThe trust model explains what a website may do on a user’s computer. This page lists how it is enforced.
Transport
Section titled “Transport”Protocol version 2. The agent always connects out, so users need no open ports. The hub offers one or both transports (transports option); the agent uses WebSocket and falls back to HTTPS streaming after three failed attempts.
- WSS (traditional mode): one WebSocket per computer. The hub pings every 10 s; a computer that misses two pings is shown offline.
- HTTPS streaming (FaaS mode, and the fallback):
POST <basePath>/agent/connectopens a link,GET <basePath>/agent/streamreturns NDJSON lines (one JSON object per line: hub frames with a sequence number, and{"ctl":"ping"}every 10 s), and the agent sends its messages withPOST <basePath>/agent/events. Every request carries the machine token as aBearerheader. The stream ends afterstream.maxDurationMsand the agent reconnects at once. Reopening with acursoracknowledges everything up to it, so a cut stream never loses a frame and never repeats an acknowledged one; upstream messages have idempotent ids, so a retry is not applied twice. - Plain
ws:///http://is refused unless the hub is onlocalhost,127.0.0.1or[::1](development). - Frames and request bodies are JSON, validated against the protocol schemas on both sides, at most 1 MiB each. The hub refuses agents older than
minAgentVersion(WebSocket:upgrade_required; HTTP:426 upgrade_required). - HTTP requests to
/agent/*, WebSocket upgrades and/machine/revokewith a missing or wrong machine token are rate limited per client IP (rateLimits.agentAuthFailuresPerMinute, 60), counted in the store. - Presence: a computer that stays silent for longer than two missed pings (about 30 s) is shown offline, on either transport.
Machine tokens
Section titled “Machine tokens”- One token per computer and website: 32 random bytes, base64url.
- Stored only on the computer, in
~/.uncage/agent.yaml(mode 0600; looser permissions are tightened). The hub stores a SHA-256 hash. - Never logged, never put in events, never sent to the browser.
- Revocable from the website (
hub.revokeMachine,DELETE <basePath>/machines/:id) and from the computer (uncage sites remove). A revoked token stops working at once and its connection is closed. - Re-pairing the same computer (it sends a random
machineKeyat pairing) rotates the token and keeps the machine id; a connection using the old token is closed.
Device login
Section titled “Device login”- User codes: 8 characters from a 31-character alphabet without look-alikes (
ABCDEFGHJKMNPQRSTUVWXYZ23456789), valid 10 minutes, single use. - Codes can only be approved by a signed-in user, through your
/devicepage, which you must protect against framing and CSRF (guide). - Rate limits: 20 device codes per minute per client IP; 10 failed code lookups or decisions per user per 10 minutes. Counted in the hub store, shared by every node and function instance.
- The device code (the CLI’s polling secret) and the user code are stored hashed.
- Phishing links: anyone can start a code on their own computer and send the link. A code from the URL is never trusted on its own: the approve page warns, shows when and from which IP the code was requested (
requestedAt,requestIp; IP only, no geolocation), and enables Approve only after the user typed the code’s last 4 characters from their terminal (guide). Apps never pre-fill a code from a custom URL scheme.
Isolation between users
Section titled “Isolation between users”- Every browser request is authenticated with
getUser(req). - Every session, run, approval, attachment and machine is looked up with its owner. Another user’s id answers
404, indistinguishable from a missing one. - A computer can only report events for its own sessions, and only call tools for runs of its own user’s sessions that were started through the hub.
- State-changing browser requests from another origin get
403 forbidden_origin.
Tool execution
Section titled “Tool execution”- Tool handlers run on your server. The computer only receives names, descriptions and JSON Schemas.
- Tool names cannot contain
__and are namespaced on the computer (mcp__site__<name>), so they can never shadow Claude Code’s built-in tools. - Arguments are validated with your zod schema before the handler runs.
- A call is accepted only for tools in the run’s manifest; each call is audited in the hub store.
requiresConfirmationtools ask the user on every call, in every permission mode.- Timeouts (120 s), a concurrency cap (8 per computer) and a result size cap (just under 1 MiB) bound the work.
File channel
Section titled “File channel”- Paths must be relative and inside the session workspace; the computer resolves them with
realpathand refuses anything outside. - Symlinks are never followed. Hard-linked files are skipped in folder pulls and refused for single files.
- At most 50 MiB per pull and 10 MiB per file; pulls are all-or-nothing.
On the user’s computer
Section titled “On the user’s computer”- Each session runs in its own folder,
~/Uncage/<site host>/<session id>/(mode 0700), never in existing projects. The browser cannot choose the folder. - Skills are written only inside
.claude/skills/<name>/of that folder, without following symlinks. bypassPermissionsneedslocalPolicy.allowBypass: trueon the computer;localPolicy.allowedPermissionModescaps the modes.- Everything a website does is in
~/.uncage/sites/<site id>/activity.log(redacted). install.shhas fixed content; it installs@uncage/clifrom npm and nothing else.
One-click connect
Section titled “One-click connect”uncage://connect?url=… can be fired by any web page, so it never connects silently. The full model is in One agent, every site; in short:
- Phishing risk. A hostile page could ask a computer to pair with the attacker’s site, where the attacker is signed in, and so bind the victim’s computer to the attacker’s account.
- Native confirmation.
uncage connectshows a dialog outside the browser with the site’s registrable domain and full URL, defaulting to Cancel; without a dialog or a terminal it refuses. Warnings: international characters (punycode shown), bare IP, a specific page, first connection, and look-alikes of connected domains. - Strict links. Only
https://(or loopbackhttp), no credentials, query or fragment, at most 2048 characters, oneurlparameter; one question at a time. After the confirmation the approval page and the answering site must match the confirmed origin. - Against a hostile site the device flow adds nothing. The site controls its own
/devicepage; the native confirmation is the only gate, and it warns that whoever runs the site can start coding-agent sessions on this computer at any time (within your local policy). - No registry. Uncage does not vouch for any site; the dialog shows facts, not a verdict.
- Handler scope. Registered per user only (macOS app in
~/Library/Application Support, a.desktopfile in~/.local/share/applications,HKCUon Windows), no admin rights, removed byuncage agent uninstall.
The local dashboard
Section titled “The local dashboard”uncage dashboard binds 127.0.0.1 on a random port. Each request needs the Host header 127.0.0.1:<port> (DNS rebinding gets 403), no foreign Origin, and a 32-byte token that appears once in the link’s fragment and is traded for an API token kept in sessionStorage (no cookie), sent in a header. State changes are POSTs from the page’s own origin. No CORS headers, X-Frame-Options: DENY, Cache-Control: no-store. It closes with the page or after 30 minutes idle. Another local process or web page without the secret gets 403; a process that can read your files can read ~/.uncage/agent.yaml anyway.
Apps and extensions
Section titled “Apps and extensions”App bearer tokens
Section titled “App bearer tokens”- A native app sends
Authorization: Bearer <token>and noOrigin; the hub lets origin-less requests through the cross-site guard on every browser-API route, because only browsers attach cookies to cross-site requests and browsers always sendOrigin. A request with a foreignOriginis refused even with a valid cookie. - Your
getUserdecides what a token is worth: issue expiring, revocable tokens, keep them in the keychain, and do not fall back to a cookie when a bearer header is invalid (authenticate apps). - The app never holds a machine token and never talks to a computer directly.
trustedOrigins(for extensions) are exact origins you control, validated bycreateHub: no wildcards, paths,file:ornull, plainhttpon loopback only. A trusted origin may make state-changing requests with the user’s cookies. It does not add CORS headers: this is for extensions and native shells, not for other web origins.POST /device/decisionaccepts onlyapplication/json, andGET /device/lookupis behind the cross-site guard and the failed-code limit.- Push tokens live in your database, never in the hub.
onAttentionfires at most once per event and skips events older than 10 minutes (push notifications).
ACP agents
Section titled “ACP agents”Other ACP agents run as local processes on the user’s computer, with their own login. What protects the user:
- Consent is bound to the full spec. An agent distributed through
npxoruvxdownloads code, so it runs only afteruncage runtimes enable <id>. The consent records the runner, the package (any version), the arguments and the environment; if the registry later runs anything else, the agent waits for a newenable. - Registry trust. An agent from the ACP registry is enabled only if it is installed on this computer and answers the ACP handshake. A registry refresh that changes the command withdraws it until you enable it again.
autoDetect: falseturns detection off;disableblocks an agent whatever else says so. - A project file cannot grant consent. In Local Mode,
enableandconsentedinuncage.config.yamlare ignored. agents[].commandin a project file runs without consent. A project’suncage.config.yamlcan list any command, anduncage servestarts it.uncage doctoranduncage serveprint every such command at start: only run them in projects you trust.- No “always”. Uncage answers an ACP permission request with the agent’s
allow_onceorreject_onceoption and never selectsallow_alwaysorreject_always, which the agent could keep outside the session. - Site tools through a loopback MCP server. Each run gets an MCP server on
127.0.0.1with a one-time bearer token, passed to the agent inmcpServers; tools withrequiresConfirmationask in Uncage before every call. Handlers still run on your server. - Skills are materialized only under
.uncage/skills/<name>/of the session folder, and listed in the first prompt. - The registry download (
cdn.agentclientprotocol.com, at most daily;UNCAGE_ACP_REGISTRY_REFRESH=0turns it off) only supplies names, commands and icons: it runs nothing by itself.
Local Mode
Section titled “Local Mode”The daemon binds to loopback only, requires a bearer token from ~/.uncage/token (mode 600), rejects foreign Origins, and is reached by browsers only through your same-origin proxy, which checks Host (DNS rebinding) and Origin. Details: Local Mode in depth.
Checklist for website developers
Section titled “Checklist for website developers”-
getUserreturns the real signed-in user, ornull; session cookies areSecureandSameSite=LaxorStrict. -
publicUrlis yourhttps://origin, and your proxy forwards the originalHost. -
/devicerequires sign-in, sendsframe-ancestors 'none'andX-Frame-Options: DENY, decides with a CSRF-protected POST, and asks for the last 4 characters of a code that came in the link. - Every tool handler scopes its reads and writes to
ctx.user.id. - Tool errors are user-safe; details go to your logs.
- Tools that publish, send, pay or delete use
requiresConfirmation: true. - Files pulled from computers are treated as untrusted (served sandboxed, scanned if needed).
- If you ship an app or extension: bearer tokens expire and are revocable,
trustedOriginslists only exact origins you control, and you do not expect users to confirm a one-click connection they did not start. - The client IP is configured for rate limits behind your proxy.
- With your own Postgres pool or Redis client,
'error'listeners are attached.