What Lantern does

Lantern lets a website send supported AI requests through the Codex or Claude CLI already signed in on your Mac. You approve the exact site first. While Lantern is running and online, it starts the CLI chosen for that connection and returns the reply to the website.

Your provider login stays inside the CLI on your Mac. Prompts, attached images, and replies pass through the website, Lantern's relay, and the provider. Codex and Claude still run online and use your normal account limits.

Before you install

You need all three of the following:

  • 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.
  • A supported CLI that is installed and signed in. Use Codex, Claude, or both.

If Codex or Claude is not installed yet, install at least one:

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 CLIs 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 looks for Codex and Claude, checks whether you are signed in, and asks which ones approved sites may use. If a CLI needs a sign-in, setup can open its sign-in flow.

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 CLI 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 and use of your account limits. Every connection can submit text prompts and receive text. A compatible Codex connection can also submit reference images and receive a generated image. The site does not receive your 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.

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, then confirm the CLI chosen for the connection is still signed in and that its account has not reached a provider 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 Codex and Claude 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 Codex or Claude 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.