One agent, every site
View as MarkdownA user installs the Uncage agent once. Every site that embeds Uncage can then use it, without another terminal: the site shows a link, the user clicks it, confirms on their own computer, and approves on the site as usual.
How it works
Section titled “How it works”uncage setup(oruncage agent install) installs the background agent and registers a handler foruncage://links with the operating system.uncage agent uninstallremoves it again.- macOS: a small per-user application,
~/Library/Application Support/Uncage/UncageConnect.app, registered with LaunchServices. No admin rights. - Linux:
~/.local/share/applications/uncage-connect.desktopandxdg-mime defaultforx-scheme-handler/uncage. Skipped with a note whenxdg-mimeis missing. - Windows:
HKCU\Software\Classes\uncage(the current user only).
- macOS: a small per-user application,
- Your site shows Already use Uncage on this computer? Connect in one click: the
<ConnectMachine>panel links touncage://connect?url=<your site>(the hub’sinstallInfo.connectUrl; hidden on mobile). The install command stays the primary path, because a page cannot tell whether the handler exists. - The OS runs
uncage connect <link>, which validates the link, shows the native confirmation and, only on Connect, starts the normal device flow: the browser opens the site’s/devicepage and the user clicks Approve. - The new site is saved in
~/.uncage/agent.yamland the background agent restarts.
You can also run it by hand: uncage connect https://app.example.com. See the CLI reference.
One-click needs @uncage/cli 0.4 or newer. An existing 0.3 install gets the handler only after npm i -g @uncage/cli@latest and running uncage agent install (or uncage setup) again, because that is the only place it is registered.
What is accepted
Section titled “What is accepted”uncage connect accepts uncage://connect?url=<site> with exactly one parameter, or a bare URL. It refuses, before anything else happens, a site URL that:
- is not
https://(plainhttp://only forlocalhost,127.0.0.1,[::1]), - carries a user name or password, a query or a fragment,
- contains spaces or control characters, or is longer than 2048 characters,
- has any other scheme (
javascript:,data:,file:) or any otheruncage://action or parameter.
The confirmation and site identity checks
Section titled “The confirmation and site identity checks”Before any pairing, a dialog on this computer asks: Connect this computer to example.com? It shows the site’s registrable domain first (from the Public Suffix List, including private suffixes such as vercel.app, so each project there is its own owner), then the full hub URL, and what connecting allows: whoever runs the site can start coding-agent sessions on this computer at any time and answer their approval prompts within your local policy, so only connect sites you trust. The warnings come before the URL, and a very long URL is shortened. Cancel is the default. The dialog is in the system language (English, Chinese or Japanese).
It adds a line for each of these:
| Warning | When |
|---|---|
| International characters | The host is an IDN; its punycode form is shown. |
| Bare IP address | The site is an IP, not a domain. |
| A specific page | The path is neither the root nor the default /api/uncage: on a shared origin a path can belong to someone other than the domain’s owner. |
| First time | This computer never connected to that registrable domain before. |
| Looks like another site | The label has the same look-alike skeleton as a connected domain (digits and Cyrillic or Greek letters mapped to Latin, rn ≈ m, …), or is within edit distance 2 of it. For names shorter than 4 characters, only a look-alike match counts. |
How the question is asked, per operating system:
| OS | Dialog |
|---|---|
| macOS | /usr/bin/osascript (an alert that gives up, as a No, after 10 minutes) |
| Windows | A message box (WScript.Shell Popup) with OK and Cancel (default Cancel), shown through the system’s own Windows PowerShell |
| Linux | zenity (preferred), else kdialog, when a display is available (DISPLAY or WAYLAND_DISPLAY). With only kdialog the buttons are “Don’t connect” (the default), Connect and Cancel |
If there is no dialog tool, or it could not be shown (no graphical session), and the command runs in a terminal, it asks Connect? [y/N] there. Without a dialog and without a terminal it refuses and prints how to run it by hand. No dialog, no connection. Also:
- Only one question at a time: a page that fires links repeatedly cannot stack dialogs.
- Every prompt, including the terminal one, counts as a No after 10 minutes.
- After the user cancels, the same domain cannot ask again for 30 seconds (for links).
- The registered handler runs
uncage connect --from-link <link>, and the outcome, connected or not and why, is shown as a system notification: on macOS in Notification Center throughosascript(notifications may need to be allowed for Script Editor), on Linux withnotify-sendwhen installed, on Windows as a message box that closes after 60 seconds (the run is hidden, so the console only flashes). - Connecting restarts the background agent, which interrupts running sessions of the other sites.
- After the user confirms, the approval page the hub announces must be on the confirmed origin, and the site that answers must be the confirmed URL; otherwise nothing is saved.
- A site’s self-declared name is never shown without its domain.
- Exit codes:
0connected,1cancelled, refused or pairing failed (Not connected: <reason>),2bad link.
The local dashboard
Section titled “The local dashboard”uncage dashboard opens a page for this computer’s connected sites:
- each site with its name and domain, machine id, connected since, status (online, offline, revoked) and transport, the runtimes it is offered, and its recent redacted activity;
- Disconnect: revokes the machine token on the site (like
uncage sites remove) and restarts the agent; - turn ACP agents on or off (the same consent as
uncage runtimes enable|disable), and a read-only view of the local policy.
It is a page on 127.0.0.1 at a random port. The link is http://127.0.0.1:<port>/#t=…: the one-time token sits in the fragment, which browsers never send to a server. The page trades it once for an API token that it keeps in sessionStorage and removes the fragment from the address bar; there is no cookie. Reloading works in that tab; another tab or browser cannot use the link again. Every request must have the right Host (127.0.0.1:<port>, which defeats DNS rebinding), no foreign Origin and the API token in a header, otherwise it gets 403. There are no CORS headers. It exits when the page is closed or after 30 minutes without a request (--no-browser prints the link instead of opening it). The page follows the system language.
Threat model
Section titled “Threat model”One-click makes a phishing attempt cheaper: any web page can fire uncage://connect?url=https://evil.example. If it worked silently, the attacker, who is signed in on their own site, would approve the victim’s computer into their account and could then drive the user’s coding agent there. What stops that:
- The native confirmation shows who is asking, outside the web page, and defaults to No. A page cannot click it.
- Identity warnings make look-alikes, IDNs, IP hosts and first-time sites stand out.
- Against a hostile site the device flow adds nothing: the site controls its own
/devicepage and can approve on its side. The native confirmation is the only gate, so confirm only sites you trust. (For an honest site the device flow still compares the code and shows the computer.) - No central registry: Uncage does not vouch for sites. The dialog shows what the link says, not a verdict; users should only confirm a connection they just started.
- What a connected site can do on the computer is unchanged: the trust model, the local policy and per-tool approvals. The dashboard shows and revokes every connection.
See the security page.