Who does what
Owns the interface, prompt, server route, and decision to make an AI request.
Starts the connection and keeps a signed cookie telling your server which Lantern the user connected and which compatible model the app chose.
Matches the request to the correct Mac and carries request and response data between the two sides.
Shows the approval page, verifies signed requests from the approved app, and starts the CLI chosen for that connection.
Processes the request through its online service using the account already signed into that CLI.
Connecting the app and sending an AI request are separate events. The user approves the exact site before it sends requests. Later requests use that approval while Lantern is running and online.
Connecting an app
Connect Lantern opens 127.0.0.1:4319/pair on the user's Mac. Lantern shows the app name and exact web origin. Approval records that origin and the app's public signing key. Localhost, preview deployments, and production domains are different origins and need separate approvals.
Lantern returns a relay ticket plus the available models and capabilities. The browser posts that result to the app's own route, which stores the ticket, chosen model, capabilities, origin, and expiry in an HMAC-signed HttpOnly cookie. Later browser requests bring the cookie back to the app server automatically.
The cookie lasts for 30 days by default. Forgetting the connection in one browser deletes that cookie; it does not remove the approval on the Mac. Stopping Lantern pauses all approved apps. Running setup again removes every approval from the saved configuration; restart Lantern for that change to take effect.
Sending a request
user uses an AI feature in the browser
→ your app server reads the signed Lantern cookie
→ your server signs the AI request
→ Lantern relay routes it to the selected Mac
→ Lantern on the Mac verifies the app and request
→ Lantern starts the signed-in Codex or Claude CLI
→ the CLI calls its provider's online service
↩ the response streams back along the same pathlantern.server(request) prepares the provider from the browser cookie. The network connection starts only when your route makes an AI SDK call. Standard text calls open one CLI session, stream the response, and close the session when the call finishes.
Credentials and content
The provider login and Lantern's local API token are not returned to apps using createLanternApp.
LANTERN_APP_SECRET identifies and signs your app. It is never sent to the browser or the Mac.
Prompts, attached images, provider output, and replies pass through your app, the relay, and the provider service.
Request signing proves which approved app sent a request; it does not hide the content from the relay. Only approve sites you trust with the content they submit and with use of the provider account's normal limits.
An approved web app can invoke Lantern's supported text, streaming, and image paths. It cannot choose an arbitrary local URL or directly submit a shell command through the server provider. Client-defined tools and structured response formats are not supported by the compatibility layer.
With guided setup, text requests start in a fresh temporary folder. Claude starts with no tools. Codex text requests use its read-only sandbox, which prevents writes but may still read through its built-in tools, the user's usual CLI configuration, and environment. Codex image requests can write only inside that temporary folder. Advanced manual configuration can change Claude's tools.
Lantern is not an offline model runtime. The CLI starts on the Mac, but Codex or Claude still contacts its provider's online service.
App server helper
lantern.server(request) connects an incoming app request to the Lantern stored in that browser's cookie. It returns the model selection and a Vercel AI SDK provider configured with the session's relay ticket.
For each call, the provider checks that the requested public model was included during pairing, then creates a 30-second Ed25519-signed execution envelope. The envelope includes the app origin, endpoint, request body, optional file count, and a one-use nonce for local verification.
Lantern relay
Your app server cannot open a direct connection to a Mac behind a home network. Lantern therefore opens an outbound connection to the relay, which can match the app's request to the correct Mac without opening a router port.
Lantern on the Mac opens an outbound WebSocket to lantern.hiltonbarber.com when it starts. It registers with a persisted Ed25519 identity, receives a time-limited relay ticket, and refreshes its presence while connected.
When your app makes an AI call, its server opens a request WebSocket and presents that ticket. The relay finds the matching Mac and forwards the request. Redis routes frames when the two WebSockets land on different Vercel Function instances. The relay carries request and response content; Lantern on the Mac performs the app-signature checks.
Lantern on the Mac
Lantern service
This local server serves the approval page at 127.0.0.1:4319. For each relayed request, it checks the app origin, public key, signature, expiry, file count, and nonce before passing the request to the matching handler.
CLI connection
A configured Codex or Claude CLI installed and signed in on the user's computer. Its provider ID is also the model name connected apps use. An adapter starts the CLI and translates its output into Lantern's shared events. See Supported CLIs.
CLIs and sessions
Model
The OpenAI-compatible view of a configured CLI connection. Lantern returns provider IDs such as codex or claude as model names after pairing, so there is no separate alias layer.
Session
One live conversation with a provider CLI. Standard AI SDK and REST text requests open a session for one call and close it when the response completes. The lower-level WebSocket interface can keep both the conversation and CLI process open for follow-up prompts.
Local access
Local access token
Setup creates a private token for REST and WebSocket clients on the same Mac. New web apps should use createLanternApp, which keeps this token out of the browser. The older pairLocalLantern() browser flow returns it to the page after approval.
Approved app origins
The exact web origins approved by the user. Pairing associates each origin with the app's public signing key in the local configuration.
Agent run
A one-turn workspace request for authenticated Node code running on the same computer as Lantern. It is a lower-level local capability alongside the standard inference APIs.