What Lantern does

Lantern lets an approved website use Apple Intelligence on your Mac, or a Codex or Claude CLI already signed in there. You approve the exact site first. While Lantern is running and online, it starts the selected model adapter and returns the reply.

Apple Intelligence performs inference on device. Codex and Claude use their online services and normal account limits. Website prompts and replies pass through the website, Lantern's relay, and your Mac in either case.

Before you install

You need the first two items and at least one model option:

  • macOS 14 or newer on an Apple silicon or Intel Mac.
  • Node.js 22 or newer. The menu bar app uses Node.js to start Lantern.
  • Apple Intelligence: macOS 26 on a supported Apple silicon Mac, with Apple Intelligence enabled.
  • Codex or Claude: install the CLI and sign in.

If you are not using Apple Intelligence, install at least one CLI:

Terminal
# Codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Claude
curl -fsSL https://claude.ai/install.sh | bash

Then run codex login or claude auth login. Lantern setup can also open the sign-in flow for an installed CLI.

Lantern is best for interactive features used while you and your Mac are present. It is not an always-on backend for scheduled or unattended work.

Install Lantern

The menu bar app runs Lantern and shows whether it is on, which models are configured, and which sites you have approved.

Download Lantern for Mac

  1. Open Lantern.dmg.
  2. Drag Lantern to Applications.
  3. Open Lantern and follow setup in Terminal.

Run setup

Terminal
npx @sunbeam-za/lantern setup

Setup checks Apple's on-device model and looks for Codex and Claude. It asks which available models approved sites may use and can open a CLI sign-in flow when needed.

When setup finishes, choose whether to start Lantern. Keep that Terminal window open if you start it there.

Connect an app

Return to the app and choose Connect Lantern. Lantern opens its own page with the app's name and site address. Check both before you approve it.

After approval, the browser remembers the connection. The site can use it while Lantern is running and online and the chosen model is available.

What approval allows

Approving a site allows future supported AI requests from that exact address. Lantern does not ask again before every prompt. Local development, preview deployments, and production use different addresses and need separate approvals.

Approve only sites you trust with the request content. Every connection can submit text prompts and receive text. A compatible Codex connection can also submit reference images and receive a generated image. Apple Intelligence does not use a provider account; Codex and Claude use normal account limits. The site does not receive a provider login.

With guided setup, text requests use 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 available tools and your usual CLI configuration. Codex image requests can write only inside that temporary folder.

Everyday controls

Lantern must be running and online for an approved site to reach this Mac. Use the menu bar app, or start and stop it from Terminal:

Terminal
npx @sunbeam-za/lantern start
npx @sunbeam-za/lantern stop

Stopping Lantern pauses every approved site. The menu cannot remove one site yet. Running setup again replaces your provider choices and removes every approval from the saved configuration. Restart Lantern for that change to take effect. The local API token stays the same.

A site's Disconnect button only forgets the connection in that browser. It does not remove the approval stored by Lantern.

Running check
curl http://127.0.0.1:4319/health

The health endpoint only confirms that Lantern is running. It does not confirm that a provider sign-in still works.

Troubleshooting

Connect Lantern does not open

Confirm that Lantern is running on this Mac and that the browser allowed the new window. Then try the button again.

Apple Intelligence is unavailable

Confirm this is a supported Apple silicon Mac running macOS 26 or newer, then enable Apple Intelligence in System Settings and wait for its model to finish downloading.

A CLI is not found

Run its command directly in Terminal. If it works there, run Lantern setup again so it can save the current command path.

A request fails after approval

Check that Lantern says it is online and the selected model is available. For a CLI, also confirm it is signed in and has not reached an account limit.

The site address changed

Connect again from the new address. Localhost, preview deployments, and production domains each need their own approval.

Local settings

~/.lantern/config.json

Your model choices, approved apps, and Lantern settings.

~/.lantern/token

The private credential for local Lantern APIs. Setup gives both files owner-only permissions.

~/.lantern/tunnel.json

The private identity Lantern uses to reconnect to its relay.

Run setup again any time to change your model choices. Restart Lantern afterward. This clears approved apps, so each site will need to connect again. Your local token stays the same.

Install from source

Terminal
git clone https://github.com/sunbeam-za/lantern.git
cd lantern && npm install
npm run build
node dist/cli.js setup

Use the source path when working on Lantern itself. For everyday use, install the Mac app above. The shorter npx command also works for a terminal-only setup.

Adding Lantern to your own app? Continue with the app guide.