Most users should run npx @sunbeam-za/lantern setup instead of editing this file. Use this reference when you need to change the local server, provider commands, or session limits yourself. Restart Lantern after changing the configuration.

Typical configuration

~/.lantern/config.json
{
  "host": "127.0.0.1",
  "port": 4319,
  "allowedOrigins": ["https://hobby.hiltonbarber.com"],
  "pairedApps": {},
  "maxSessions": 2,
  "providers": {
    "codex": { "adapter": "codex-app-server" },
    "claude": {
      "adapter": "claude-cli",
      "safeMode": true,
      "tools": []
    }
  }
}

Setup writes these fields to ~/.lantern/config.json on the user's Mac. Connecting an app updates allowedOrigins and pairedApps. A source checkout can use sunbeam.config.json in its startup directory.

Server settings

host

Defaults to 127.0.0.1, the fixed local destination used for pairing and direct local APIs.

port

Defaults to 4319. Use 0 in tests to select a free port.

allowedOrigins

The exact web origins approved by the user, such as https://hobby.example.com. The Connect Lantern flow adds an origin automatically.

pairedApps

The public signing keys approved through Connect Lantern. Lantern binds each entry to that app's exact origin.

maxSessions

Cap on live provider conversations (sessions), counted across all clients. Defaults to 2.

maxPromptChars

Maximum prompt length. Defaults to 32,000 characters.

Provider settings

Each provider describes one CLI connection that approved apps may use. The provider key is also the model name exposed to apps. adapter selects codex-app-server, codex-cli, or claude-cli. command can override the executable path, and model can choose a provider-native model understood by that CLI.

Provider models
"providers": {
  "codex": { "adapter": "codex-app-server" },
  "codex-cli": { "adapter": "codex-cli" },
  "claude": { "adapter": "claude-cli", "safeMode": true, "tools": [] }
}

Provider model names

Lantern derives its model catalog from providers; there is no second alias map to keep in sync. Setup creates the provider IDs codex and claude. Pairing returns those IDs, and your app sends one in the AI SDK model field.

The optional model inside a provider selects a model understood by that CLI. It does not create another public model name.

Provider-native model
"providers": {
  "claude": {
    "adapter": "claude-cli",
    "model": "claude-sonnet-4-5",
    "safeMode": true,
    "tools": []
  }
}

Session defaults

Standard app sessions start in fresh temporary directories and clean them up when the session closes. Codex runs with its read-only sandbox. Claude runs in safe mode with tools: [], which becomes --tools "".

i

Read-only is not file-blind. It stops Codex from writing files, but Codex may still read through its available tools and starts with the user's usual CLI configuration and environment. Claude starts with no tools.

Trusted local Node processes can add a workspace and access level to one request through the chat API's agent extension or POST /v1/agent/runs. This keeps ordinary generation simple while supporting deliberate local workspace tasks.

Upgrading from 0.1

Lantern 0.2 removed project mappings, and the current format also removes the redundant top-level models map. A former one-to-one map such as codex → codex is accepted during migration but omitted from loaded configuration. Separate model aliases are no longer supported: name the provider with the model ID your app should use.