Installation

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

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.