Next.js on Vercel (FaaS mode)
View as MarkdownOn Vercel the hub runs inside a Next.js route handler: no custom server, no WebSocket, no second service. Every function instance is a hub; they share one Postgres database, and users’ computers connect over HTTP streaming (a long request the hub ends before Vercel’s time limit, reopened by the agent at once). The same files run under next start anywhere. Why FaaS mode, and what it costs: Choose a deployment mode.
Prerequisites
Section titled “Prerequisites”- A Next.js 15.1 or newer app with the App Router (the files below use
afterfromnext/server), on Vercel. - A Postgres database reachable from Vercel: Neon, Supabase, Vercel’s Postgres integrations, or your own. Its connection string becomes
DATABASE_URL. A pooled URL (Neon’s-poolerhost, PgBouncer) is fine and recommended. - Your app’s sign-in, readable from a
Request(the hub) and fromcookies()(your pages).
npm i @uncage/hub @uncage/react-ui pg zodnpm i -D @types/pgSeven files. Paths are relative to your project root.
Who is signed in
Section titled “Who is signed in”import type { HubUser } from '@uncage/hub';
/** * Replace both functions with your real sign-in before you deploy. * `userFromRequest` is used by the hub (a Fetch `Request`); `currentUser` by your pages. */export async function userFromRequest(_req: Request): Promise<HubUser | null> { return developmentUser();}
export async function currentUser(): Promise<HubUser | null> { return developmentUser();}
function developmentUser(): HubUser { if (process.env.NODE_ENV === 'production') { throw new Error('lib/auth.ts still returns the development user: connect it to your sign-in.'); } return { id: 'dev-user', name: 'Developer' };}The hub
Section titled “The hub”One hub per function instance, created on the first request (so next build never connects to the database) and shared by the route handler and your pages.
import { createHub, postgresCluster, postgresHubStore, type Hub } from '@uncage/hub';import pg from 'pg';import { userFromRequest } from './auth.ts';
async function createAppHub(): Promise<Hub> { const url = process.env.DATABASE_URL; if (!url) throw new Error('DATABASE_URL is not set: add your Postgres connection string to the project’s environment variables.'); const publicUrl = process.env.PUBLIC_URL ?? (process.env.VERCEL ? undefined : 'http://localhost:3000'); if (!publicUrl) throw new Error('PUBLIC_URL is not set: add your site’s https:// origin to the project’s environment variables.'); // One small pool per function instance, shared by the store and the cluster. const pool = new pg.Pool({ connectionString: url, max: 5 }); pool.on('error', (err) => console.error('postgres pool error:', err.message)); // required for your own pool const store = await postgresHubStore({ pool }); return createHub({ publicUrl, // what users open; localhost only outside Vercel getUser: userFromRequest, store, cluster: postgresCluster({ pool }), // wake-ups between function instances, through Postgres sessionStorage: 'site', // End long responses (agent streams, browser events) before the route's maxDuration (300 s). stream: { maxDurationMs: 250_000 }, // A site tool runs inside one request: keep its limit well inside maxDuration. toolTimeoutMs: 120_000, // Enables GET /api/uncage/maintenance for Vercel Cron (it sends Authorization: Bearer $CRON_SECRET). ...(process.env.CRON_SECRET ? { maintenance: { secret: process.env.CRON_SECRET } } : {}), });}
const KEY = Symbol.for('my-site.uncage-hub');type Holder = { [KEY]?: Promise<Hub> };
/** The hub of this function instance. A failed start (database briefly down) is retried on the next call. */export function getHub(): Promise<Hub> { const g = globalThis as Holder; const hub = (g[KEY] ??= createAppHub()); hub.catch(() => { if (g[KEY] === hub) delete g[KEY]; }); return hub;}The route handler
Section titled “The route handler”import { toNextHandlers } from '@uncage/hub';import { after } from 'next/server';import { getHub } from '../../../../lib/uncage-hub.ts';
// `after`: the hub's background work (maintenance) never delays a response.export const { GET, POST, PATCH, DELETE } = toNextHandlers(getHub, { waitUntil: after });
/** Seconds a request may run on Vercel. The hub ends its streams earlier (stream.maxDurationMs). */export const maxDuration = 300;export const dynamic = 'force-dynamic';export const runtime = 'nodejs';toNextHandlers passes each request to hub.fetch with:
- the client IP for per-IP rate limits: on Vercel (the
VERCELenvironment variable is set) the address Vercel’s edge puts inx-real-ip, which clients cannot spoof there. Anywhere else, passclientIp: (req) => …yourself; waitUntil: Next’safter, so maintenance runs after the response and a site tool call finishes even if the agent’s request drops.
The chat page
Section titled “The chat page”'use client';import { AgentChat, UncageProvider } from '@uncage/react-ui';import '@uncage/react-ui/styles.css';
export default function UncagePage() { return ( <div style={{ height: '100vh' }}> <UncageProvider> <AgentChat /> </UncageProvider> </div> );}The approval page
Section titled “The approval page”Where uncage setup sends the user to approve their computer. Signed-in only, never framed, decided with a Server Action (a POST that Next.js accepts only from your own origin). The same files as in the quickstart, with await getHub().
import type { ApproveDeviceProps } from '@uncage/react-ui';import { currentUser } from '../../lib/auth.ts';import { getHub } from '../../lib/uncage-hub.ts';import { ApprovePage } from './approve-page.tsx';
export const dynamic = 'force-dynamic';
type DeviceError = NonNullable<ApproveDeviceProps['error']>;
export default async function DevicePage({ searchParams }: { searchParams: Promise<{ code?: string }> }) { const { code = '' } = await searchParams; const user = await currentUser(); if (!user) return <p>Sign in first, then open this link again.</p>; // or redirect to your login page let lookup: ApproveDeviceProps['lookup'] = null; let error: DeviceError | undefined; try { lookup = code ? await (await getHub()).lookupDevice(code, user) : null; } catch (e) { // Unknown codes count as failed guesses; after 10 in 10 minutes lookupDevice throws `rate_limited`. const err = e as { code?: string; message?: string }; error = { code: err.code === 'rate_limited' ? 'rate_limited' : 'internal_error', message: err.message ?? 'Could not check this code.' }; } return <ApprovePage code={code} lookup={lookup} initialError={error} />;}'use server';import { currentUser } from '../../lib/auth.ts';import { getHub } from '../../lib/uncage-hub.ts';
export type DecideResult = { result: 'ok' | 'not_found' | 'expired' } | { error: { code: string; message: string } };
/** A Server Action: a POST that Next.js only accepts from this site's own Origin. */export async function decide(code: string, approve: boolean): Promise<DecideResult> { const user = await currentUser(); if (!user) return { error: { code: 'unauthorized', message: 'Sign in again.' } }; try { const hub = await getHub(); return { result: await (approve ? hub.approveDevice(code, user) : hub.denyDevice(code, user)) }; } catch (e) { const err = e as { code?: string; message?: string }; return { error: { code: err.code ?? 'internal_error', message: err.message ?? 'Failed' } }; }}'use client';import { ApproveDevice, type ApproveDeviceProps, type ApproveDeviceState } from '@uncage/react-ui';import '@uncage/react-ui/styles.css';import { useState } from 'react';import { decide } from './actions.ts';
export function ApprovePage({ code, lookup, initialError,}: Pick<ApproveDeviceProps, 'code' | 'lookup'> & { initialError?: ApproveDeviceProps['error'] }) { const [state, setState] = useState<ApproveDeviceState>('idle'); const [error, setError] = useState<ApproveDeviceProps['error']>(initialError); const act = async (approve: boolean) => { setState(approve ? 'approving' : 'denying'); setError(undefined); const r = await decide(code, approve); if ('error' in r) { setState('idle'); // the buttons stay enabled for a retry setError(r.error as ApproveDeviceProps['error']); } else { setState(r.result === 'ok' ? (approve ? 'approved' : 'denied') : r.result); } }; return <ApproveDevice code={code} lookup={lookup} state={state} error={error} onApprove={() => void act(true)} onDeny={() => void act(false)} />;}Headers and the cron
Section titled “Headers and the cron”import type { NextConfig } from 'next';
const config: NextConfig = { async headers() { return [ { source: '/:path*', headers: [ { key: 'Content-Security-Policy', value: "frame-ancestors 'none'" }, { key: 'X-Frame-Options', value: 'DENY' }, ], }, ]; },};
export default config;{ "crons": [{ "path": "/api/uncage/maintenance", "schedule": "0 4 * * *" }] }Maintenance (retention cleanup, failing tool calls whose instance died) also runs by itself on ordinary requests, at most once a minute across all instances, through after. The cron is a safety net for quiet periods. Vercel Hobby allows one run a day; Pro can run it hourly or more often.
Environment variables
Section titled “Environment variables”Set them in the Vercel project (Settings → Environment Variables) for Production and Preview, and in .env.local for next dev.
| Variable | Required | What it is |
|---|---|---|
DATABASE_URL |
yes | Your Postgres connection string. Pooled URLs (Neon -pooler, PgBouncer in transaction mode) work. The hub creates its tables on the first request. |
PUBLIC_URL |
yes | The exact origin users open, for example https://app.example.com (your production domain, not a preview URL). It goes into the install and setup commands. |
CRON_SECRET |
recommended | A random string (openssl rand -hex 32). Vercel Cron sends it as Authorization: Bearer …; the hub’s /maintenance endpoint exists only when it is set. |
| Your auth secrets | yes | Whatever lib/auth.ts needs. |
Deploy
Section titled “Deploy”- Create the database. For example Neon through the Vercel Marketplace (it sets
DATABASE_URLfor you), or any Postgres 14+. Pick a region close to your Vercel functions’ region: every poll is a round trip. - Set the environment variables above.
- Deploy: push to the connected Git repository, or
npx vercel --prod. - Open your site at
/uncage, connect a computer, and work through the checklist below.
To try it on your own machine first: next build && next start with a local Postgres (docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=uncage postgres:16-alpine and DATABASE_URL=postgres://postgres:uncage@localhost:5432/postgres).
Verify
Section titled “Verify”Replace https://your.site with your PUBLIC_URL.
-
curl -s https://your.site/api/uncage/agent/infolists only thehttptransport:{"protocol":2,"minAgentVersion":"0.3.0","transports":[{"kind":"http","url":"https://your.site/api/uncage/agent"}]} -
curl -s https://your.site/api/uncage/install.sh | head -2prints#!/usr/bin/env bashand# Uncage installer…. -
curl -s -o /dev/null -w '%{http_code}\n' https://your.site/api/uncage/maintenanceprints401(withCRON_SECRETset;404without). With the secret,curl -s -H "Authorization: Bearer $CRON_SECRET" https://your.site/api/uncage/maintenanceanswers{"ran":true,…}(or"ran":falseif another instance ran it within the last minute). -
Connect a computer from
/uncage(the page shows the commands to run; approve the code on/device). It shows online within a few seconds. -
Send a prompt. The answer streams. The agent’s log (
uncage agentin a terminal, or~/.uncage/logs/agent.log) showshttp stream rotatedabout every 250 s, and the chat keeps working across rotations. -
Vercel’s function logs show no
504on/api/uncage/agent/stream. Streams end with status 200 before 300 s.
I see 504 errors (FUNCTION_INVOCATION_TIMEOUT)
Section titled “I see 504 errors (FUNCTION_INVOCATION_TIMEOUT)”A request ran longer than maxDuration. Keep stream.maxDurationMs below maxDuration, with a margin of about 50 s: maxDuration = 300 → 250_000 (the default). If you lower maxDuration (to 60, say), lower stream.maxDurationMs too (10_000 less, at least). Pro plans may raise maxDuration to 800; you can raise stream.maxDurationMs with it, but there is little gain: a rotation costs one reconnect.
maxDuration vs stream.maxDurationMs vs toolTimeoutMs
Section titled “maxDuration vs stream.maxDurationMs vs toolTimeoutMs”maxDuration(seconds, inroute.ts) is Vercel’s hard limit for any request to the route.stream.maxDurationMsis when the hub itself ends its long responses (agent streams and browser event streams) so clients reconnect cleanly. It must be belowmaxDuration.toolTimeoutMsis how long one site tool handler may run. Each tool call is handled during one request from the agent, underafter(or Vercel’s request-contextwaitUntil), so a dropped request does not stop it; but that work is still bounded bymaxDuration, sotoolTimeoutMsmust fit inside it, including any file pull. If Vercel stops the function mid-handler, the call fails with “Site tool “” timed out on the website. Please try again.” and is never re-run (at most once).
Attachments over about 4 MB fail
Section titled “Attachments over about 4 MB fail”Vercel refuses request bodies over about 4.5 MB with its own 413 before the hub sees them. The hub itself accepts 10 MiB. Users get a generic error unless you check Content-Length on POST /api/uncage/sessions/:id/attachments first and answer the hub’s attachment_too_large shape; the reference demo’s route handler does this with a 4 MB limit. Agent traffic is never affected: the agent sends at most 1 MB per request and pulls files in chunks.
Uploads fail on slow connections with 400
Section titled “Uploads fail on slow connections with 400”A request body is refused with 400 when no bytes arrive for bodyTimeoutMs (30 s by default), or when it takes more than 4 times that in total. The timer restarts on every chunk, so a slow but steady upload gets through and you rarely need to change it; keep it below maxDuration.
Neon: which driver?
Section titled “Neon: which driver?”Use pg (as above) or Neon’s @neondatabase/serverless Pool (postgresHubStore({ pool }) accepts either). Do not use the HTTP-only neon() function: the hub needs transactions on one connection. The pooled -pooler URL is fine: the hub’s migrations take transaction-scoped locks, which work behind transaction-mode poolers.
Does Neon’s free tier ever go to sleep?
Section titled “Does Neon’s free tier ever go to sleep?”Not while a computer is online or a function instance is warm: open agent streams and postgresCluster poll every 0.3 to 2 s. Budget for an always-on compute while you have users connected, or see what FaaS mode costs.
Do I need Redis?
Section titled “Do I need Redis?”No. Add it (cluster: redisCluster({ url: process.env.REDIS_URL! }), install ioredis) for lower latency and less database polling with many instances. Upstash Redis works if it speaks the Redis protocol over TCP (rediss://).
Rate limits behind another proxy
Section titled “Rate limits behind another proxy”toNextHandlers reads x-real-ip, which Vercel’s edge sets. If another proxy or CDN sits in front of Vercel, that header holds the proxy’s address: pass toNextHandlers(getHub, { waitUntil: after, clientIp: (req) => req.headers.get('cf-connecting-ip') ?? undefined }) with your proxy’s client-IP header.
Users see “Agent update needed”
Section titled “Users see “Agent update needed””Their computer runs an agent older than 0.3, which cannot connect over HTTP streaming. The page shows the fix: npm i -g @uncage/cli@latest, then the setup command again. See Troubleshooting.
Can a site tool handler run for minutes?
Section titled “Can a site tool handler run for minutes?”Not on Vercel: it runs inside one request, limited by maxDuration. Start the long work as a background job and return an id the model can check with a second tool, or host the hub in traditional mode.