Cloudflare Workers (FaaS mode)
View as MarkdownA Worker cannot keep objects that do I/O (database sockets) between requests, so on Workers the hub is created per request: fetchOnce builds a hub on a fresh Postgres pool, serves the request, and closes both once the response has finished (streams included). Everything that must outlive a request lives in Postgres, reached through Hyperdrive. Users’ computers connect over HTTP streaming. Why FaaS mode: Choose a deployment mode.
Prerequisites
Section titled “Prerequisites”- A Cloudflare account and
wrangler4.158 or newer (npm i -D wrangler). Older versions do not accept thecompatibility_datebelow. - A Postgres database reachable from Cloudflare (Neon, Supabase, your own), and a Hyperdrive configuration for it. Locally, any Postgres (for example in Docker).
- Your site’s sign-in, readable from a
Requestinside the Worker (a session cookie you can verify).
npm i @uncage/hub pgnpm i -D wrangler @types/pgFour files.
name = "my-site"main = "src/worker.ts"compatibility_date = "2026-10-01"# For the pg driver only (TCP sockets); @uncage/hub itself uses Web APIs only.compatibility_flags = ["nodejs_compat"]
[vars]PUBLIC_URL = "http://localhost:8787" # set your deployed origin before going live
[[hyperdrive]]binding = "HYPERDRIVE"id = "<your Hyperdrive id>" # wrangler hyperdrive create … --caching-disabled prints itlocalConnectionString = "postgres://postgres:uncage@127.0.0.1:5432/postgres" # used by wrangler dev
# Maintenance (retention cleanup) once a day; requests also run it opportunistically.[triggers]crons = ["0 4 * * *"]import type { HubUser } from '@uncage/hub';import type { Env } from './hub.ts';
/** * Your sign-in: the user a request belongs to, or null. Replace the body with a real check of * your session cookie, for example a signed token verified with crypto.subtle, or a lookup in * your session table. Until then, only local development (wrangler dev) has a user. */export async function userFromRequest(req: Request, env: Env): Promise<HubUser | null> { const local = ['localhost', '127.0.0.1'].includes(new URL(req.url).hostname); if (local && env.PUBLIC_URL.startsWith('http://localhost')) return { id: 'dev-user', name: 'Developer' }; return null;}import { createHub, postgresCluster, postgresHubStore, type Hub } from '@uncage/hub';import pg from 'pg';import { userFromRequest } from './auth.ts';
export interface Env { /** Hyperdrive binding (wrangler.toml); wrangler dev uses its localConnectionString. */ HYPERDRIVE: { connectionString: string }; /** The Worker's public origin, e.g. https://my-site.example.workers.dev. */ PUBLIC_URL: string;}
/** A pool for one request: Workers forbid reusing sockets across requests. At most 5 connections. */export function newPool(env: Env): pg.Pool { const pool = new pg.Pool({ connectionString: env.HYPERDRIVE.connectionString, max: 5 }); // workerd closes a finished request's sockets; pg reports that on idle clients. Log anything else. pool.on('error', (err) => { if (!/socket has been closed/i.test(err.message)) console.error('postgres pool error:', err.message); }); return pool;}
/** The hub for one request on `pool`, and the cleanup of what was built for it (the pool is the caller's). */export async function makeHub(env: Env, pool: pg.Pool): Promise<{ hub: Hub; close(): Promise<void> }> { const store = await postgresHubStore({ pool }); const cluster = postgresCluster({ pool }); const close = async () => { await cluster.close(); await store.close(); // leaves the pool open }; try { const hub = await createHub({ publicUrl: env.PUBLIC_URL, getUser: (req) => userFromRequest(req, env), store, cluster, sessionStorage: 'site', }); return { hub, close }; } catch (e) { await close(); throw e; }}import { fetchOnce } from '@uncage/hub';import { userFromRequest } from './auth.ts';import { makeHub, newPool, type Env } from './hub.ts';
/** The part of Workers' ExecutionContext used here (`wrangler types` generates the full one). */interface ExecutionContext { waitUntil(p: Promise<unknown>): void;}
export default { async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> { const url = new URL(req.url); if (url.pathname.startsWith('/api/uncage/')) { return fetchOnce( async (defer) => { const pool = newPool(env); defer(() => pool.end()); // runs after the response, also if building the hub fails return makeHub(env, pool); }, req, // Bound: an unbound ctx.waitUntil throws "Illegal invocation". { waitUntil: ctx.waitUntil.bind(ctx), clientIp: req.headers.get('cf-connecting-ip') ?? undefined }, ); } if (url.pathname === '/device') return devicePage(req, url, env, ctx); return new Response('Your website'); },
/** Cron Trigger: run the hub's maintenance (it skips if another instance ran it within the minute). */ async scheduled(_event: unknown, env: Env, ctx: ExecutionContext): Promise<void> { const pool = newPool(env); const work = (async () => { const { hub, close } = await makeHub(env, pool); try { console.log('uncage maintenance', JSON.stringify(await hub.maintain())); } finally { await hub.close(); await close(); } })().finally(() => pool.end()); ctx.waitUntil(work); },};
/** /device: where a signed-in user approves `uncage setup`'s code. Never framed; POST from this origin only. */async function devicePage(req: Request, url: URL, env: Env, ctx: ExecutionContext): Promise<Response> { const user = await userFromRequest(req, env); if (!user) return page('<p>Sign in first, then open this link again.</p>', 401); if (req.method === 'POST' && req.headers.get('origin') !== url.origin) return page('<p>Cross-site request refused.</p>', 403); const pool = newPool(env); try { const { hub, close } = await makeHub(env, pool); try { if (req.method === 'POST') { const form = await req.formData(); const code = String(form.get('code') ?? ''); const approve = form.get('decision') === 'approve'; // The code came in a link (anyone can send one): approve only with its last 4 characters typed. const tail = String(form.get('tail') ?? '').toUpperCase().replace(/[\s-]/g, ''); if (approve && tail !== code.toUpperCase().replace(/[\s-]/g, '').slice(-4)) { return page('<p>The last 4 characters do not match. Check your terminal and try again.</p>', 400); } const result = approve ? await hub.approveDevice(code, user) : await hub.denyDevice(code, user); if (result === 'ok') return page(approve ? '<p>Approved. You can close this tab.</p>' : '<p>Denied.</p>'); return page(`<p>This code is ${result === 'expired' ? 'expired' : 'unknown'}. Run <code>uncage setup</code> again.</p>`, 410); } const code = (url.searchParams.get('code') ?? '').trim(); // Exactly what the CLI prints: padding such as ABCD-EFGH---- is not a valid link. if (!/^[A-Z0-9]{4}-?[A-Z0-9]{4}$/i.test(code)) return page('<p>This link is not valid. Run <code>uncage setup</code> again.</p>', 400); const info = await hub.lookupDevice(code, user); if (!info) return page('<p>Unknown or expired code. Run <code>uncage setup</code> again.</p>', 404); const repair = info.repairsMachine ? `<p>This re-pairs <b>${esc(info.repairsMachine.name)}</b>.</p>` : ''; const ip = info.requestIp ? ` · IP as seen by the server: ${esc(info.requestIp)}` : ''; const asked = `<p>Requested ${esc(info.requestedAt)}${ip}. Name and system: reported by the computer, not verified.</p>`; return page( `<form method="post"><p><b>Only approve if you just ran <code>uncage setup</code> on a computer in front of you. Never approve a code someone sent you.</b></p>` + `<p>Connect <b>${esc(info.name ?? 'a computer')}</b> to your account?</p>${asked}${repair}` + `<label>Type the last 4 characters shown in the terminal of a computer you are sitting at. If someone gave you these characters, choose Deny. <input name="tail" autocomplete="off" required></label>` + `<input type="hidden" name="code" value="${esc(code)}"><button name="decision" value="approve">Approve</button> <button name="decision" value="deny" formnovalidate>Deny</button></form>`, ); } finally { await hub.close(); await close(); } } catch (e) { // Unknown codes count as failed guesses: after 10 in 10 minutes the hub refuses with rate_limited. if ((e as { code?: string }).code === 'rate_limited') return page('<p>Too many attempts. Try again in a few minutes.</p>', 429); console.error('device page failed:', e); return page('<p>Something went wrong. Try again shortly.</p>', 500); } finally { ctx.waitUntil(pool.end()); }}
function page(body: string, status = 200): Response { return new Response(`<!doctype html><meta charset="utf-8"><title>Connect your computer</title>${body}`, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "frame-ancestors 'none'", 'x-frame-options': 'DENY' }, });}
function esc(s: string): string { return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);}What matters here:
- One hub per request.
fetchOnce(create, req, …)callscreate(defer)for every request. Register cleanups withdeferas you open things; return the hub, or{ hub, close }. After the response body has finished or was cancelled (never earlier, so streams keep working), it runshub.close(), thenclose, then the deferred cleanups. - Migrations are checked once per isolate: a fresh pool costs one cheap
SELECT max(id), no lock and no DDL. waitUntil: ctx.waitUntil.bind(ctx)keeps the isolate alive for site tool calls whose request dropped, the hub’s background work and the cleanup. Always pass it.clientIpfromcf-connecting-ip, which Cloudflare sets, for per-IP rate limits.- Your sign-in goes in
getUser(src/auth.ts). The repository example has a demo sign-in that lets anyone become any user; it refuses to work on a public host, and it is not something to copy into a real site.
Environment variables
Section titled “Environment variables”| Name | Kind | What it is |
|---|---|---|
HYPERDRIVE |
Hyperdrive binding | Your Postgres, through Hyperdrive ([[hyperdrive]] in wrangler.toml). wrangler dev uses localConnectionString instead, or the CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE environment variable. |
PUBLIC_URL |
var | The exact origin users open, https://… (plain http:// only for localhost). It goes into the install and setup commands. |
| Your auth secrets | secret | Whatever src/auth.ts needs: wrangler secret put <NAME>. For wrangler dev, put them in .dev.vars. |
No CRON_SECRET is needed: the Cron Trigger calls scheduled directly. (If you prefer an HTTP cron, set maintenance: { secret } in createHub and call GET /api/uncage/maintenance with Authorization: Bearer <secret>.)
Deploy
Section titled “Deploy”-
Run it locally first. Start a Postgres matching
localConnectionString, then:Terminal window docker run -d --name pg -p 5432:5432 -e POSTGRES_PASSWORD=uncage postgres:16-alpinenpx wrangler dev # http://localhost:8787 -
Create the Hyperdrive configuration with query caching off (the hub polls with repeated identical queries and needs fresh results) and put its id in
wrangler.toml:Terminal window npx wrangler loginnpx wrangler hyperdrive create my-site-db --connection-string="postgres://user:password@host:5432/db" --caching-disabled -
Deploy once to learn your Worker’s URL:
npx wrangler deploy. -
Set
PUBLIC_URLinwrangler.tomlto that URL (or your custom domain), add your auth secrets withwrangler secret put, and deploy again. -
Wire your real sign-in into
src/auth.tsbefore you send anyone the link.
Verify
Section titled “Verify”Replace https://my-site.example.workers.dev with your PUBLIC_URL (or use http://localhost:8787 under wrangler dev).
-
curl -s https://my-site.example.workers.dev/api/uncage/agent/infolists onlyhttp:{"protocol":2,"minAgentVersion":"0.3.0","transports":[{"kind":"http","url":"https://my-site.example.workers.dev/api/uncage/agent"}]} -
curl -s https://my-site.example.workers.dev/api/uncage/install.sh | head -2prints the installer’s first lines. -
npx wrangler tailwhile you connect a computer (uncage setup https://my-site.example.workers.dev, approve on/device): no errors, and the computer shows online. -
Run a prompt that calls one of your site tools; the tool step completes.
-
npx wrangler deploy --dry-run --outdir distbundles without errors. (The root@uncage/hubentry is Web-standard and@uncage/hub/nodeis never imported here; onlypgneedsnodejs_compat.)
Why a new hub for every request? Isn’t that slow?
Section titled “Why a new hub for every request? Isn’t that slow?”Workers forbid sharing sockets between requests, so a shared pool is not an option. Building a hub is cheap: no migrations after the first request of an isolate (one SELECT max(id)), and Hyperdrive keeps the real database connections warm. The repository example measured about 350 ms for a command’s round trip through the stream on workerd.
Do site tools run exactly once on Workers?
Section titled “Do site tools run exactly once on Workers?”On Workers the hub runs each tool call under the waitUntil you pass to fetchOnce, so a dropped POST does not stop the handler: its result is stored and the agent’s resend gets it (exactly once). Workers keeps waitUntil work alive for only about 30 s after the client disconnects. A handler still running after that is cancelled. Once its lease runs out (toolTimeoutMs + 10 s), the call fails with “Site tool “waitUntil, any dropped POST leads to this. So: always pass waitUntil: ctx.waitUntil.bind(ctx), keep handlers well under 30 s, and make them idempotent where you can.
504s or streams cut early?
Section titled “504s or streams cut early?”HTTP Workers have no wall-clock limit while the client stays connected, and waiting on I/O does not count as CPU time, so the default stream.maxDurationMs (250 s) is fine. If your plan or a proxy in front cuts long requests earlier, lower stream.maxDurationMs below that limit.
Neon or Supabase without Hyperdrive?
Section titled “Neon or Supabase without Hyperdrive?”Use Hyperdrive: it pools connections close to the Worker. Create it with --caching-disabled: the hub polls with repeated identical queries and needs fresh results, which Hyperdrive’s query cache would serve stale. Without it, Neon’s @neondatabase/serverless Pool (WebSockets) also works with postgresHubStore({ pool }); its HTTP-only neon() function does not (the hub needs transactions on one connection).
Why nodejs_compat?
Section titled “Why nodejs_compat?”Only for pg, which opens TCP sockets through cloudflare:sockets. @uncage/hub’s root entry uses Web APIs only; @uncage/hub/node (WebSocket server, PGlite) is never bundled.
Can computers use WebSockets here?
Section titled “Can computers use WebSockets here?”Not with this setup: nothing in a Worker accepts the agents’ WebSockets (that would need Durable Objects). The hub offers only http, and agents use it. An agent older than 0.3 that tries a WebSocket gets 426 upgrade_required and the site shows “Agent update needed”.
Rate limits behind another proxy?
Section titled “Rate limits behind another proxy?”cf-connecting-ip is the client address as Cloudflare saw it. With another proxy in front of Cloudflare, read that proxy’s client-IP header instead.