Skip to content
Lantern

Background daemon

Terminal window
uv run lantern daemon install     # install and start the LaunchAgent (starts at login)
uv run lantern daemon run         # or run the daemon in the foreground (Ctrl+C stops it)
uv run lantern pending            # files found by the daemon, waiting for approval
uv run lantern approve | decline  # index them / ask again on the next change
uv run lantern pause | resume
uv run lantern config index_mode auto   # index right away instead of asking (default: ask)
uv run lantern daemon stop | uninstall
  • On start (also after a long shutdown) the daemon scans all folders: deleted files leave the index at once; new and changed ones wait for approval in “ask” mode. While running, FSEvents report changes.
  • Indexing runs in a separate background-priority process: the audio, vision and Whisper models live only there and are released when it finishes. The idle daemon uses ~490 MB. Searches run at a higher priority than the daemon’s own scans, so they stay fast while it works (measured in DECISIONS.md, “Power and QoS”).
  • Automatic pause on battery power, in Low Power Mode and when macOS reports the Mac is hot (thermal state “serious” or worse), and when less than 2 GB is free on the disk of the index; the current file is finished, the rest waits. lantern status shows what the daemon sees.
  • A stuck file never stops the queue: a file the worker spends more than 30 minutes on (90 for a transcript; e.g. a hung PDF or image decoder) is skipped with the reason in lantern status and the warnings, and indexing goes on with the next one.
  • Settings live in ~/Library/Application Support/Lantern/config.toml (lantern config lists them).
  • API: Unix socket ~/Library/Application Support/Lantern/lantern.sock (mode 0600, folder 0700), JSON lines. The menu bar app uses the same API.
  • Logs: ~/Library/Application Support/Lantern/logs/ (paths and errors, never file contents or queries).