Node (traditional mode)
View as MarkdownTraditional mode is the hub inside a Node.js process that keeps running: a VM, a container, Railway, Fly.io, Render or your own server. It needs no external service: the hub keeps its data in an embedded Postgres (PGlite) folder, and users’ computers hold a WebSocket to it. Not sure this is your mode? See Choose a deployment mode.
Prerequisites
Section titled “Prerequisites”- Node.js 22.18 or newer: it runs the
.tsserver below directly, without a build step (older versions need--experimental-strip-types, or compile withtscfirst). - A host that keeps the process running and gives it a persistent disk for the hub’s data folder (
.uncage-hub). Without one, every restart forgets the paired computers and users must rununcage setupagain. - In front of it, a proxy or load balancer that forwards WebSocket upgrades on
/api/uncage/agent(most hosts do by default) and serveshttps://. - Your app’s sign-in, readable from a Fetch
Request(a session cookie).
npm i @uncage/hub expressTwo files. auth.ts stands for your sign-in; replace its body.
import type { HubUser } from '@uncage/hub';
/** Your sign-in: the user a request belongs to, or null. */export async function getSessionUser(req: Request): Promise<HubUser | null> { const cookie = req.headers.get('cookie') ?? ''; // Look the session cookie up in your session store here. return cookie.includes('session=') ? { id: 'user-123', name: 'Ada' } : null;}import { createServer } from 'node:http';import { createHub } from '@uncage/hub';import { attachWebSocket, pgliteHubStore, toNodeHandler } from '@uncage/hub/node';import express from 'express';import { getSessionUser } from './auth.ts';
const port = Number(process.env.PORT ?? 3000);
// Embedded Postgres in a folder: one process per folder, kept across restarts.const store = await pgliteHubStore({ dataDir: process.env.UNCAGE_DATA_DIR ?? './.uncage-hub' });const hub = await createHub({ publicUrl: process.env.PUBLIC_URL ?? `http://localhost:${port}`, getUser: getSessionUser, store, sessionStorage: 'site', // keep a copy of every conversation on your site});
const app = express();if (process.env.TRUST_PROXY) app.set('trust proxy', Number(process.env.TRUST_PROXY)); // proxies in front: req.ip is the clientapp.use(toNodeHandler(hub)); // first, before express.json() or compression()app.use(express.json());app.get('/', (_req, res) => { res.send('Your website');});
const server = createServer(app);attachWebSocket(hub, server); // computers connect to ws(s)://<host>/api/uncage/agentserver.listen(port, () => console.log(`ready on http://localhost:${port}`));
// On deploy or restart: stop taking requests, let running site tools finish, then close the store.process.once('SIGTERM', () => { server.close(); void hub .close() .then(() => store.close()) .finally(() => process.exit(0));});What each piece does:
toNodeHandler(hub)serves everything under/api/uncage(the browser API, the device login,install.shandinstall.ps1, and the HTTP streaming transport) and passes other paths tonext(). It hands the hubreq.ipfor per-IP rate limits.attachWebSocket(hub, server)accepts the computers’ WebSockets on the same HTTP server and runs the hub’s maintenance (retention cleanup) every minute. With it, the hub offers both transports: agents use WebSocket, and fall back to HTTP streaming by themselves if WebSockets keep failing (a proxy that blocks upgrades, for example).hub.close()never closes yourstore: close it after the hub.
Using Fastify, Hono or a Next.js custom server instead of Express? Mount the hub has a complete server for each. Next.js on its own: the Connected Mode quickstart builds this setup into a Next.js app.
Environment variables
Section titled “Environment variables”| Variable | Required | What it is |
|---|---|---|
PUBLIC_URL |
yes, in production | The exact origin users open, for example https://app.example.com. It goes into the install and setup commands, so it must be https:// (plain http:// only for localhost). |
PORT |
no | The port to listen on (default 3000). |
UNCAGE_DATA_DIR |
no | The hub’s PGlite folder (default ./.uncage-hub). Put it on the persistent disk. Add it to .gitignore. |
TRUST_PROXY |
behind a proxy | The number of proxies in front of the app, for app.set('trust proxy', …). Without it, every user shares one rate-limit bucket (see the FAQ). |
These names are this page’s choice; the hub itself reads no environment variables.
Deploy
Section titled “Deploy”-
Build and start with
node server.ts(Node 22.18+). In a container, for example:Dockerfile # Node 22.18 or newer runs server.ts directly (type stripping); node:22 is the latest 22.x.FROM node:22-slimWORKDIR /appCOPY package*.json ./RUN npm ci --omit=devCOPY . .ENV UNCAGE_DATA_DIR=/data/uncage-hubVOLUME /dataEXPOSE 3000CMD ["node", "server.ts"] -
Give it a persistent volume at the data folder (
/dataabove). Railway, Fly.io and Render call it a volume or disk. -
Set
PUBLIC_URLto yourhttps://origin, andTRUST_PROXY=1if a proxy or load balancer sits in front (it almost always does on a platform). -
Check the proxy in front:
- forwards WebSocket upgrades on
/api/uncage/agent, with an idle timeout above 30 s (the hub pings every 10 s); - does not buffer
text/event-streamresponses (browser events) orapplication/x-ndjsonones (agent streams); - keeps the original
Hostheader.
nginx, for example:
nginx.conf (excerpt) location / {proxy_pass http://127.0.0.1:3000;proxy_http_version 1.1;proxy_set_header Host $host;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";proxy_buffering off;proxy_read_timeout 300s;} - forwards WebSocket upgrades on
-
Run one process per data folder. PGlite locks its folder. For more than one process, see Multi-node.
Verify
Section titled “Verify”Replace https://your.site with your PUBLIC_URL.
-
curl -s https://your.site/api/uncage/install.sh | head -2prints#!/usr/bin/env bashand# Uncage installer…. -
curl -s https://your.site/api/uncage/agent/infolists both transports,wsfirst:{"protocol":2,"minAgentVersion":"0.3.0","transports":[{"kind":"ws","url":"wss://your.site/api/uncage/agent"},{"kind":"http","url":"https://your.site/api/uncage/agent"}]}Only
http?attachWebSocketdid not run in this process. -
curl -s -o /dev/null -w '%{http_code}\n' https://your.site/api/uncage/healthprints401(signed out). Signed in, the browser gets{"ok":true,…}. -
On a computer, run the command your page shows (or
uncage setup https://your.site), approve the code on/device, and the page shows the computer online. -
Restart the server: the computer comes back online within about 30 s without a new
uncage setup(the data folder survived).
My site is on Vercel or Netlify. Can I still use traditional mode?
Section titled “My site is on Vercel or Netlify. Can I still use traditional mode?”Yes, as a separate service. Run this server on a host with WebSockets, and route https://your.site/api/uncage/* including WebSocket upgrades to it at your edge (a load balancer, Cloudflare, nginx in front of both), so it is the same origin as your site: the browser API relies on your site’s cookies and same-origin checks. Vercel rewrites do not proxy WebSockets (agents then fall back to HTTP streaming, which works but loses the instant delivery). In getUser, verify your site’s session cookie without your framework’s helpers (for example the signed JWT your auth library issues). Your /device approval page needs hub.approveDevice, which lives in this process: serve /device from it too, or expose a small authenticated, CSRF-protected endpoint your page calls. Often simpler: use FaaS mode on Vercel directly.
uncage setup fails with 429 rate_limited for many users at once
Section titled “uncage setup fails with 429 rate_limited for many users at once”Behind a proxy the hub sees the proxy’s address unless told otherwise, so all users share one bucket of 20 device codes per minute. Set TRUST_PROXY (above), or pass rateLimits: { clientIp: (req) => req.headers.get('x-real-ip') ?? undefined } with your proxy’s client-IP header. Details: behind a proxy.
The proxy blocks WebSockets. Does it still work?
Section titled “The proxy blocks WebSockets. Does it still work?”Yes. After three failed WebSocket attempts the agent switches to HTTP streaming (served by the same toNodeHandler) and tries WebSocket again every 30 minutes. Fix the proxy anyway: WebSocket delivers commands instantly and costs less.
Can I use Postgres instead of PGlite?
Section titled “Can I use Postgres instead of PGlite?”Yes: store: await postgresHubStore({ connectionString: process.env.DATABASE_URL! }) (install pg). Do it when you want managed backups or more than one node. Pooled connection strings (PgBouncer, Neon -pooler) work: migrations use transaction-scoped locks.
Do I need Redis?
Section titled “Do I need Redis?”Not for one process. For several nodes, add redisCluster (or postgresCluster) as shown in Multi-node.
A deploy restarted the server. What happened to running work?
Section titled “A deploy restarted the server. What happened to running work?”Computers reconnect by themselves (backoff from 1 s up to 30 s). Runs keep going on the users’ computers and their events backfill on reconnect. A site tool handler still running when the process stops fails with “Site tool “hub.close() gives running handlers toolDrainMs (5 s) to finish first.
Old agents (0.2) cannot connect
Section titled “Old agents (0.2) cannot connect”The hub tells them to upgrade (upgrade_required) and 0.2 agents upgrade themselves with npm i -g @uncage/cli@latest. See Troubleshooting.