Quickstart: Local Mode
View as MarkdownLocal Mode is for apps that run on the same machine as the agent: a developer dashboard, an internal tool, a desktop-style app. The daemon uncage serve runs Claude Code under that machine’s Claude login; your app reaches it through a same-origin proxy that adds the daemon token on the server.
If your users each have their own computer, use Connected Mode instead.
Copy prompt for your coding agent
Section titled “Copy prompt for your coding agent”Add Uncage Local Mode to this Next.js (App Router) app, following https://uncage-dev.vercel.app/docs/start/quickstart-local.md exactly.1. npm i @uncage/server @uncage/react-ui @uncage/cli2. Create app/api/uncage/[...path]/route.ts with createUncageHandler from @uncage/server/proxy (runtime 'nodejs', dynamic 'force-dynamic', export GET, POST, PATCH).3. Create a page that renders <UncageProvider><AgentChat /></UncageProvider> from @uncage/react-ui inside a full-height container, and import '@uncage/react-ui/styles.css'.Do not expose the daemon token to the browser and do not call the daemon from client code directly.Verify: run "npx uncage doctor" and report each line; with "npx uncage serve --workspace <this repo>" running in another terminal and the app on http://localhost:3000, curl -s http://localhost:3000/api/uncage/runtimes returns a JSON array that contains "claude".1. Prerequisites
Section titled “1. Prerequisites”- macOS, Linux or Windows, and Node.js 22 or newer (
node -v).uncage serveruns wherever the CLI does; macOS is verified on real devices, Linux and Windows are CI verified and await real-device confirmation. - Claude Code installed and signed in:
npm i -g @anthropic-ai/claude-code, then runclaudeonce and type/login. - A Next.js (App Router) app. Starting fresh:
npx create-next-app@latest my-app(TypeScript, App Router).
2. Install
Section titled “2. Install”npm i @uncage/server @uncage/react-ui @uncage/cli3. Add two files
Section titled “3. Add two files”The route handler is a same-origin proxy. It reads the daemon token on the server, so the token never reaches the browser.
import { createUncageHandler } from '@uncage/server/proxy';
export const runtime = 'nodejs';export const dynamic = 'force-dynamic';export const { GET, POST, PATCH } = createUncageHandler();'use client';import { AgentChat, UncageProvider } from '@uncage/react-ui';import '@uncage/react-ui/styles.css';
export default function Page() { return ( <div style={{ height: '100vh' }}> <UncageProvider> <AgentChat locale="en" /> </UncageProvider> </div> );}locale is 'en' (the default) or 'zh-CN'.
4. Start the daemon
Section titled “4. Start the daemon”Leave it running in its own terminal:
npx uncage serve --workspace /absolute/path/to/the/project/the/agent/works/in--workspace is the folder the agent reads and edits. On first start the daemon creates ~/.uncage/token (mode 600) and ~/.uncage/data, then prints:
Uncage listening on http://127.0.0.1:4783 · workspace /…/project · runtimes: claude ✓, codex ✗ (not installed)Check everything with npx uncage doctor. Every line is ✓ or ✗, and every ✗ prints the exact fix: command. Codex showing “not installed” is fine; it is optional.
5. Run your app
Section titled “5. Run your app”npm run devOpen http://localhost:3000, pick Claude Code, and ask something like “Scan this repo and run the tests”.
- Commands and file edits show an approval card: Allow once / Deny.
- Stop cancels the run and kills its processes.
- Refresh any time:
<AgentChat>keeps the open conversation in?session=<id>, so history and pending approvals come back.
How it fits together
Section titled “How it fits together”flowchart LR B["Browser<br/>AgentChat"] -- "/api/uncage/*<br/>same origin" --> P["Your app's server<br/>createUncageHandler"] P -- "Bearer token<br/>127.0.0.1:4783" --> D["uncage serve<br/>daemon"] D --> C["Claude Code<br/>this machine's login"]
The browser talks only to your app. Your app’s server forwards to the daemon on 127.0.0.1:4783 with the token. The daemon runs Claude Code on the same machine. It is not a multi-tenant cloud service: don’t expose it to the internet or share one Claude login among many users.
Other frameworks
Section titled “Other frameworks”- Fetch-style servers (Remix / React Router, SvelteKit, Hono, Bun):
createUncageHandler()returns standard(Request) => Promise<Response>handlers. Mount them under/api/uncage/*(or passbasePath). - Express, Connect, Fastify,
node:http: usecreateUncageNodeHandler()from@uncage/server/proxy, mounted before any body parser:
import express from 'express';import { createUncageNodeHandler } from '@uncage/server/proxy';
const app = express();app.use('/api/uncage', createUncageNodeHandler()); // before express.json() and compression()app.listen(3000);- A Vite or webpack SPA with a separate backend: keep the browser’s
Hostin the dev proxy (changeOrigin: false). WithchangeOrigin: trueevery POST gets 403forbidden_origin, because the proxy comparesOriginwith the rewrittenHost.
Local Mode in depth covers the composer, attachments, configuration (uncage.config.yaml) and the Local Mode security model. The CLI reference lists every flag.
- Custom UI with hooks: build your own chat with
@uncage/react. - Troubleshooting:
forbidden_origin, ports, sign-in.