Skip to content

Installation & Setup

Jump to bottom
Matt Lucas edited this page Jun 24, 2026 · 1 revision

Installation & Setup

Quick Start

Prerequisites

  • macOS with iTerm2
  • Rust 1.70+ (brew install rust or via rustup)
  • Temporal CLI (brew install temporal-cli)
  • Git (usually pre-installed)
  • Agent CLI (at least one: claude, codex, kimi, gemini, agy, or goose)

Install Lantern

git clone https://github.com/Palmetto-Interactive-LLC/Lantern.git
cd Lantern
./scripts/install.sh
source ~/.zshrc

The installer:

  1. Creates ~/.lantern/ directory structure
  2. Builds Lantern from source with cargo build --release
  3. Installs the binary to ~/.lantern/bin/lantern
  4. Registers a launchd service for automatic startup on login

Verify Installation

lantern doctor

Output should show all systems green (Rust, Temporal, iTerm2, git, agent CLIs).

Directory Structure

After installation, Lantern uses:

~/.lantern/
├── bin/lantern              # Main executable
├── data/
│   ├── relay/lantern.db     # SQLite state store
│   └── temporal/            # Temporal dev server data (optional)
├── logs/                    # Service logs
├── config/                  # Configuration (rarely used)
└── run/                     # Runtime state (pidfiles, sockets)

Reinstall After Source Changes

If you modify the Lantern source code, rebuild and reinstall:

cargo build --release
cp target/release/lantern ~/.lantern/bin/lantern
lantern restart

This restarts the launchd service with the new binary.

Service Management

Start Services

lantern up

Starts the Relay daemon and optional Temporal dev server.

Stop Services

lantern down

Stops the Relay daemon and Temporal dev server.

Restart Services

lantern restart

Useful after rebuilding from source or to recover from a crashed service.

Troubleshooting Installation

"lantern: command not found"

Make sure your shell has sourced ~/.zshrc:

source ~/.zshrc

"Rust not found"

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then reload your shell environment:

source ~/.cargo/env
source ~/.zshrc

"Temporal CLI not found"

Install Temporal CLI:

brew install temporal-cli

"iTerm2 not found"

Lantern requires iTerm2 (not Terminal.app). Install from https://iterm2.com/ or:

brew install iterm2

"Build failed"

Make sure you have Rust 1.70+ and all dependencies:

rustc --version
cargo --version
temporal --version
git --version

See the Troubleshooting page for more help.

Clone this wiki locally