Lokei

lokei

Local dev proxy with HTTPS and named .test domains. Run lokei run next dev and get https://myapp.test automatically — with valid TLS, DNS resolution, and port forwarding.

Setup

Before using lokei, confirm it is installed:

lokei --version

If not installed, tell the user:

lokei is not installed. Install it with:

npm i -g lokei && lokei setup

lokei setup runs once — it generates a local CA, trusts it in your OS keychain, configures DNS resolution for .test domains, and sets up port forwarding.

Do NOT install or run setup automatically. Wait for the user to confirm before proceeding.

After installation, verify setup is complete:

lokei doctor

If lokei doctor reports issues, guide the user through fixing them. Common issues:

• CA not trusted → re-run lokei setup
• DNS resolver missing → re-run lokei setup
• Port forwarding inactive → re-run lokei setup (requires sudo)

Core Commands

Run a dev server with HTTPS

lokei run <command>

This is the primary command. It:

1. Starts the daemon if not running
2. Reads package.json, detects the framework (Next.js, Vite, Rails, Django, etc.)
3. Reserves a sticky port from the 4000–5999 range
4. Spawns the dev server with the correct PORT and host flags injected
5. Waits for TCP bind (30s timeout)
6. Generates a TLS certificate for <name>.test signed by the local CA
7. Registers the route — https://<name>.test is live

Examples:

lokei run                    # Auto-detects: reads package.json scripts
lokei run next dev           # Explicit command
lokei run --name myapp       # Override project name → myapp.test
lokei run --port 3000        # Use specific port instead of auto-assigned
lokei run --expose           # Also create a public tunnel

The project name is inferred from (in order): --name flag, package.json name, git remote, or directory name.

Share localhost publicly

lokei share --port <port>

Creates an ad-hoc public tunnel. No login required for random subdomain URLs.

lokei share --port 3000                          # Random URL at lokei.dev
lokei share --port 3000 --subdomain myapp        # Request specific subdomain
lokei share --port 3000 --password secret123     # Password-protected
lokei share --port 3000 --ttl 3600               # Expires in 1 hour

Run with public tunnel

lokei run --expose

Combines local HTTPS and public tunnel. Gives you both:

• https://myapp.test (local)
• https://<username>.lokei.dev/myapp (public, if logged in)

Docker Compose integration

lokei docker up              # HTTPS domains for all Compose services
lokei docker down            # Tear down

Each Compose service gets <service>.test with HTTPS. No port mapping needed.

Multi-service orchestration

lokei up                     # Start services from .test.yaml
lokei down                   # Stop all services

Define services in .test.yaml:

services:
  web:
    cmd: next dev
    name: myapp
  api:
    cmd: node server.js
    name: api
    port: 3001

Manage routes and tunnels

lokei routes ls              # List active .test routes
lokei tunnel list            # List active tunnels
lokei tunnel close <id>      # Close a tunnel
lokei inspect                # Open traffic inspector at inspect.test

Authentication (for stable tunnel URLs)

lokei login                  # Device-code auth → opens browser

After login, tunnels get stable URLs at <username>.lokei.dev.

OS service mode

lokei service install        # Install as launchd/systemd service
lokei service start          # Start the service
lokei service stop           # Stop the service
lokei service status         # Check service state
lokei service logs           # View daemon logs

Diagnostics

lokei doctor                 # Check CA, DNS, ports, trust store
lokei logs                   # View traffic logs
lokei logs --follow          # Stream logs in real-time

Cleanup

lokei uninstall              # Remove everything: certs, DNS, ports, trust

Framework Detection

lokei detects 30+ frameworks and injects the correct port and host flags:

For unlisted frameworks, lokei sets PORT environment variable and the dev server should respect it.

Git Worktree Support

When using git worktrees:

• Main branch → myapp.test
• Feature branch in worktree → fix-ui.myapp.test

The prefix is added automatically when multiple worktrees exist.

Key Architecture Details

• State directory: ~/.lokei/ — CA certs, leaf certs, routes.json, ports.json, daemon socket
• Port range: 4000–5999 (sticky across restarts, file-locked ledger)
• TLD: .test (RFC 2606 reserved)
• DNS: Local resolver on 127.0.0.1:15353, wired via /etc/resolver/test on macOS
• Port forwarding: 80→15080, 443→15443 via pfctl (macOS), iptables (Linux)
• TLS: Per-host exact-match certs via SNI (no wildcards)
• IPC: JSON over Unix socket (macOS/Linux), Named Pipe (Windows)
• Tunnel relay: WebSocket + MessagePack at relay.lokei.dev

When to Use Each Command

Common Patterns for AI Agents

When helping a user set up a project for local development:

1. Check if lokei is installed (lokei --version)
2. Check if setup is complete (lokei doctor)
3. Run the dev server: lokei run (auto-detects framework)
4. The URL will be https://<project-name>.test

When the user wants to share their work:

1. If already running with lokei run, suggest lokei run --expose next time
2. For quick sharing: lokei share --port <port>
3. For stable URLs: lokei login first, then lokei run --expose

When debugging:

1. Run lokei doctor to check system health
2. Check lokei routes ls for active routes
3. Use lokei inspect to view traffic
4. Check lokei logs for daemon output