lokl

Define your entire local dev environment in a single file. Start everything with lokl up.

Documentation

---

Why lokl?

New developer joins your team. Instead of spending a day setting up their environment:

lokl up

That's it. Frontend, backend, databases, HTTPS routing — all running.

How it compares

	lokl	docker-compose	overmind / foreman	Tilt
HTTPS with local domains, auto-certs	✅	—	—	—
Native processes (no container)	✅	—	✅	partial
Containers	✅	✅	—	✅
Health checks & dependency order	✅	✅	—	✅
Interactive TUI	✅	—	—	web UI
Works without Kubernetes	✅	✅	✅	—

lokl runs your native processes and containers side by side, behind one HTTPS reverse proxy with auto-generated certificates — all from one config file.

Features

🚀 Single config file — Define all services in lokl.yaml

🔐 Automatic HTTPS — Generated certificates for custom domains (app.myproject.dev)

🔄 Process management — Health checks, dependency ordering, auto-restart

🐳 Docker support — Run databases and caches as containers alongside your services

🔑 Env files & interpolation — Load secrets from .env files, reference with ${VAR}

🖥️ Interactive TUI — Start/stop services, view logs, toggle proxy

🔍 Project detection — lokl init scans your project and generates config

Installation

Homebrew (macOS/Linux):

brew install shahin-bayat/tap/lokl

One-liner:

curl -fsSL https://raw.githubusercontent.com/shahin-bayat/lokl/main/install.sh | bash

Go install:

go install github.com/shahin-bayat/lokl/cmd/lokl@latest

Quick Start

# Initialize config from your project
lokl init

# Start your environment
lokl up

Example Config

name: my-project
version: "1"

proxy:
  domain: myproject.dev

services:
  frontend:
    command: pnpm dev
    path: apps/frontend
    port: 5173
    subdomain: app

  api:
    command: pnpm dev
    path: apps/api
    port: 3000
    subdomain: api
    env:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/myproject
    depends_on:
      - db

  db:
    image: postgres:16
    ports:
      - "5432:5432"
    port: 5432
    env_file:
      - .env
    env:
      POSTGRES_DB: myproject
    health:
      command: "pg_isready -U myproject"  # exec-based check (no HTTP endpoint)
      interval: 2s
      retries: 10

Then:

• https://app.myproject.dev → frontend (port 5173)
• https://api.myproject.dev → api (port 3000)

Going further

The documentation covers the full config and CLI reference, including:

• Wildcard subdomains — *.myshop.dev for multi-tenant apps
• Proxy-only services — multiple HTTPS endpoints for one container
• Container networking — containers reach each other by service name
• Overriding a container's command

Requirements

• macOS or Linux
• Go 1.25+ (for installation from source)
• Docker (for container-based services)

Contributing

See CONTRIBUTING.md.

License

MIT