agentleFS
ulpi-ioulpi-io/browse/.agents/skills/lokei/SKILL.md

lokei

Skill15 starsChanged 8 months agoApache-2.0View on GitHub

Local dev proxy that gives projects named HTTPS domains on .test with valid TLS. Use when setting up local development environments, running dev servers, sharing localhost publicly via tunnels, or managing Docker Compose services with HTTPS. Handles framework detection (30+ frameworks), port management, DNS, certificates, and public tunnels. Trigger on: "run my dev server", "set up HTTPS locally", "share localhost", "expose my app", "local dev proxy", "tunnel", ".test domain", or when helping users start/configure web projects.

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 7 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before using lokei, confirm it is installed:

    line 22
  2. Distinctive:

    If not installed, tell the user:

    line 28
  3. Distinctive:

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

    line 38
  4. Distinctive:

    After installation, verify setup is complete:

    line 40
  5. Very specific:

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

    line 46
  6. Very specific:

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

    line 147
  7. Distinctive:

    When using git worktrees:

    line 195
  8. Distinctive:

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

    line 229
  9. Very specific:

    Check if lokei is installed (lokei --version)

    line 231
  10. Very specific:

    Check if setup is complete (lokei doctor)

    line 232
  11. Very specific:

    Run the dev server: lokei run (auto-detects framework)

    line 233
  12. Distinctive:

    When the user wants to share their work:

    line 236
  13. Very specific:

    If already running with lokei run, suggest lokei run --expose next time

    line 237
  14. Very specific:

    Run lokei doctor to check system health

    line 242
  15. Very specific:

    Check lokei routes ls for active routes

    line 243
  16. Very specific:

    Use lokei inspect to view traffic

    line 244
  17. Very specific:

    Check lokei logs for daemon output

    line 245

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

FrameworkDetectionFlags injected
Next.jsnext dev--port PORT
Vitevite, vite dev--port PORT --host 127.0.0.1
Astroastro dev--port PORT --host 127.0.0.1
Railsrails server-p PORT -b 127.0.0.1
Djangopython manage.py runserver127.0.0.1:PORT
Laravelphp artisan serve--port=PORT --host=127.0.0.1
Flaskflask run--port PORT --host 127.0.0.1
Angularng serve--port PORT
Nuxtnuxt dev--port PORT
Hugohugo server--port PORT
npm/yarn/pnpm/bunScript runnerPORT env var

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

ScenarioCommand
Start working on a projectlokei run
Start with explicit commandlokei run next dev
Share with a teammatelokei share --port 3000 or lokei run --expose
Docker projectlokei docker up
Multiple serviceslokei up (requires .test.yaml)
Debug network issueslokei inspect
Check what's runninglokei routes ls
Something brokenlokei doctor
Run on bootlokei service install
Remove everythinglokei uninstall

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.