Installation

Clone, start the stack, verify it's healthy — under two minutes.

In plain termsThe "stack" is everything Lantern needs to run on your laptop: a database that remembers your agents and their runs (Postgres), a fast in-memory helper for live updates (Redis), file storage for agent bundles (MinIO), the API server that does the work, and the dashboard you'll use in the browser. One command starts all of it — you don't need to know how any individual piece works to use Lantern.

Prerequisites

Tool	Min version	Homebrew
Docker Desktop	v4.x+	`brew install --cask docker`
Node.js	v20+	`brew install node`
Go	v1.23+	`brew install go`
Git	any	`brew install git`

Docker must be running before you start. Postgres, Redis, and MinIO run in Docker containers.

Clone the repo

git clone https://github.com/dshakes/lantern.git
cd lantern

Start the stack

One command boots everything:

lantern dev

Or run services individually for faster iteration:

# Terminal 1 — Postgres, Redis, MinIO
make dev-infra

# Terminal 2 — control-plane API on :8080
make run-api

# Terminal 3 — Next.js dashboard on :3001
make dashboard-dev

Never run go run ./cmd/server directly. It uses OS-user Postgres auth and will fail. Always use make run-api — it injects DATABASE_URL, REDIS_URL, and S3_ENDPOINT.

Verify

curl -s http://localhost:8080/healthz
# → {"status":"ok"}

make dev-doctor   # probes every service and reports status

Dev credentials

Seeded automatically on first boot. No setup required.

Service	Value
PostgreSQL	`postgres://lantern:lantern@localhost:5432/lantern?sslmode=disable`
Redis	`redis://localhost:6379`
MinIO	`http://localhost:9000` · console `:9001` · creds `lantern / lanternsecret`
Dashboard	`admin@lantern.dev` / `lantern` at localhost:3001
JWT secret	`lantern-dev-jwt-secret-do-not-use-in-production`
Dev tenant ID	`00000000-0000-0000-0000-000000000001` (slug: `dev`)
Dev user ID	`00000000-0000-0000-0000-000000000002` (role: `owner`)

Never use these credentials in production. Rotate all secrets before any production deployment.

Service ports

Service	Port	Protocol
control-plane (HTTP)	`:8080`	REST + health + SSE
control-plane (gRPC)	`:50051`	gRPC
dashboard	`:3001`	Next.js / Turbopack
workflow-engine	`:50052`	gRPC
model-router	`:50053`	gRPC
runtime-manager	`:50054`	gRPC
runtime-scheduler	`:50055` / `:8085`	gRPC / REST
gateway	`:8443`	HTTPS
surface-gateway	`:8444`	HTTP webhooks
PostgreSQL	`:5432`	postgres
Redis	`:6379`	redis
MinIO S3	`:9000`	S3-compatible
MinIO console	`:9001`	HTTP browser

Make targets

Target	What it does
`make dev`	Full docker-compose stack
`make dev-infra`	Postgres + Redis + MinIO only (daily driver)
`make dev-doctor`	Health-check every service
`make run-api`	Control-plane on `:8080`
`make dashboard-dev`	Next.js dashboard on `:3001`
`make run-whatsapp-bridge`	WhatsApp bridge on `:3100`
`make build`	Compile Go + Rust + TypeScript
`make test`	All test suites
`make lint`	All linters
`make ci-local`	Lint + test + audit (same as CI)
`make proto`	Regenerate from `.proto` definitions
`make clean`	Remove artifacts + docker volumes

Next steps

Quickstart

Create your first agent and run it end-to-end.

Agents

Instructions, tools, visual editor.

Deployment

Production with Helm, Terraform, or Lantern Cloud.