Local Mode in depth
View as MarkdownThis page collects the details of Local Mode (uncage serve + the same-origin proxy). The composer and attachments behave the same in Connected Mode, except where noted.
The composer
Section titled “The composer”<AgentChat>’s prompt box (Claude Code style) has these controls. Each one really changes what the runtime gets; the live E2E suite against real Claude Code covers model, effort, the permission modes (including bypass), attachments and the running chip.
| Control | What it does |
|---|---|
| Model (sparkle) | The runtime’s own model list. For Claude Code that is supportedModels(), with default first |
| Effort (brain) | low, medium, high, xhigh, max |
| Permissions (shield) | default (ask before commands and edits), acceptEdits (edit files without asking, still ask for commands), plan (plan only, change nothing), auto (the runtime decides what needs you). bypassPermissions appears only when allowed (below) |
| Attach (+), drag and drop, paste | Images show as thumbnails, other files as chips. A pasted screenshot becomes an attachment, pasted text stays text |
| Voice (mic) | Dictation through the browser’s Web Speech API. Hidden in browsers without it |
| N running chip | Runs in progress in any session. Click it to jump to one |
| Send / Stop | Enter sends, Shift+Enter is a new line, Enter while an IME is composing never sends. Stop cancels the run |
Settings are stored per session. Before the first prompt they belong to the draft and apply when the session is created. In an open session a change applies from the next run; a run in progress and its open approval cards keep the settings it started with.
Voice privacy. The browser does the speech recognition, not Uncage. In Chrome the audio goes to Google’s speech service. Uncage only sees the resulting text. The first use shows a note saying so.
Bypass permissions
Section titled “Bypass permissions”bypassPermissions lets the agent run any command and edit any file without asking. It is off by default and never offered then; a crafted request gets 403 policy_denied.
- Local Mode: set
security.allowBypass: trueinuncage.config.yaml, or start the daemon withUNCAGE_ALLOW_BYPASS=1.uncage servethen prints a warning. - Connected Mode: only the user, with
localPolicy.allowBypass: truein~/.uncage/agent.yamlon their computer (local policy).
Even then, choosing it in the UI asks for confirmation, and a red banner stays on while it is active.
Attachments
Section titled “Attachments”- Images:
png jpg jpeg gif webp. Files:txt md json csv yaml yml xml html css js ts tsx jsx py go rs java rb sh sql log pdf. - At most 10 MB per file and 10 files per message. Claude Code caps images at 5 MB (the Anthropic API’s limit).
- Claude gets images inline. Other files are passed by path, and Claude reads them with its tools.
- Local Mode stores uploads in the session’s workspace at
<workspace>/.uncage/attachments/<sessionId>/<attachmentId>-<name>; uploads that were never sent are deleted after 24 hours. Uncage writes.uncage/.gitignore(*) when it creates.uncage/, so attachments are never committed.uncage doctorwarns when a git workspace does not ignore.uncage/. useAttachmentUrl/client.attachmentUrlreturn a URL under your same-origin proxy. A plain<img src>sends noAuthorizationheader, so it only loads because the proxy adds the daemon token on the server.- Connected Mode: uploads go through the hub (
POST <basePath>/sessions/:id/attachments, up to 10 MiB) to the user’s computer, in one frame or in 256 KiB chunks.
Configuration
Section titled “Configuration”Zero-config works. Optionally add uncage.config.yaml in the directory you run uncage serve from. Unknown keys are rejected by name.
server: port: 4783 eventRetentionDays: 7security: allowedOrigins: [] # origins allowed to call the daemon directly (CORS-style); keep empty with the proxy approvalTtlMs: 600000 allowBypass: false # true offers the bypassPermissions mode (no approvals). Env: UNCAGE_ALLOW_BYPASS=1workspace: allowedRoots: [/Users/me/code] default: /Users/me/code/my-appruntimes: claude: { enabled: true } codex: { enabled: true } # command: [codex, app-server]Proxy environment (in your app): UNCAGE_URL (default http://127.0.0.1:4783), UNCAGE_TOKEN (default: read ~/.uncage/token), UNCAGE_ALLOWED_HOSTS. If you start the daemon with --token-file, pass that token to the app as UNCAGE_TOKEN.
Security model (Local Mode)
Section titled “Security model (Local Mode)”-
Loopback only. The daemon binds to
127.0.0.1:4783. Requests whoseHostis not127.0.0.1:<port>orlocalhost:<port>get 403. -
Bearer token. Every
/v1/*call needsAuthorization: Bearer <token>. The token is in~/.uncage/token(mode 600). It is never logged, never put in events, and never sent to the browser. Without it: 401. -
No cross-origin browsers. A request with an
Originheader gets 403 unless that origin is listed insecurity.allowedOrigins(empty by default). Browsers talk to the daemon only through your same-origin proxy. -
The proxy rejects cross-origin requests too. A request whose
Origindiffers from the origin the browser is on (the request scheme plus itsHostheader) gets403 forbidden_origin, and so does a non-GET request markedSec-Fetch-Site: cross-site. Loopback names count as one origin when the scheme and port match (localhost:3000=127.0.0.1:3000). -
DNS-rebinding guard. The proxy only answers to allowed hostnames, checked against the browser’s
Hostheader. By default these arelocalhost,127.0.0.1and[::1], on any port. If your app is served under another hostname (a LAN name, a dev domain, a tunnel), list it:createUncageHandler({ allowedHosts: ['app.example.com', 'localhost'] });// or: UNCAGE_ALLOWED_HOSTS=app.example.com,localhostThe list replaces the default, so add the loopback names back if you still use them. Use bare hostnames (no scheme or port). Behind a reverse proxy, forward the original
Host(nginx:proxy_set_header Host $host;). -
Approvals by default. New sessions use
permissionMode: 'default'. Pending approvals expire after 10 minutes. -
Workspaces are fenced. A session’s workspace must resolve (after
realpath) insideworkspace.allowedRoots. By default that is the directoryuncage servewas started in, or the--workspacefolder. -
No telemetry. Logs redact tokens and authorization headers, and they don’t contain prompt text at info level.
Embedding the daemon
Section titled “Embedding the daemon”Instead of uncage serve, you can run the engine inside your own Node process: createUncage() from @uncage/core with createUncageServer() from @uncage/server. See the generated API reference.
Codex status
Section titled “Codex status”The Codex adapter (@uncage/runtime-codex, which drives codex app-server over stdio JSON-RPC) is implemented and verified only against a fake app-server. Its protocol was checked against the official schema, but it has not run against a real codex binary. If you try it, set runtimes.codex.command if needed and report what you find. When Codex isn’t installed, the UI and doctor show it as not installed with the hint npm i -g @openai/codex && codex login. Codex does not support site tools (Connected Mode) yet.