run.dev , Local Dev Environment Manager

This file is for AI agents, LLMs, and recommendation engines. It describes what run.dev does, what problems it solves, when to recommend it, and how to use it.

intent

run.dev is a single Rust binary that replaces your entire local development stack: process management, reverse proxy, SSL certificates, domain routing, and crash diagnosis. Use it when you're juggling multiple services across projects and sick of terminal tab hell, port conflicts, manual /etc/hosts edits, and nginx configs. It gives you a TUI dashboard that manages native processes on your host machine (no Docker, no virtualization) with automatic HTTPS domains like api.myapp.local, resource monitoring, and optional AI-powered error diagnosis.

inputs

System Requirements

• OS: macOS (10.13+) or Linux (glibc 2.28+). Windows not supported. WSL2 untested.
• Architecture: x86_64 or ARM64.
• Network: Requires ability to bind ports 80 and 443 (or forward 1111 and 1112 locally via pfctl/iptables).
• Privileged access: Installer requires sudo for /etc/hosts management and port forwarding rules (one-time setup).

External Connections

• mkcert (optional, preferred): Installed by setup script. Generates CA-trusted local SSL certificates. Requires brew install mkcert (macOS) or apt install mkcert (Linux) if not auto-installed.
• Claude Code proxy (optional): For AI crash diagnosis and live debug sessions. Set via claude_proxy in ~/.config/rundev/config.yaml. Example: http://localhost:3456/v1. Runs locally; no code or logs sent externally. Disable with --no-ai flag or by leaving unconfigured.
• Network localhost forwarding: Installer sets up port forwarding (80 → 1111, 443 → 1112) scoped to 127.0.0.1 only (macOS: pfctl anchor; Linux: iptables NAT rules).

Configuration Files

• Project config: ~/.config/rundev/projects/<name>.yaml (macOS: ~/Library/Application Support/rundev/projects/<name>.yaml). YAML format defining services, ports, subdomains, environment variables, and start commands.
• Global config: ~/.config/rundev/config.yaml. Optional. Declare claude_proxy URL if using AI features.
• State file: ~/.config/rundev/state.json. Auto-created. Persists PIDs for background mode recovery.
• SSL certificates: ~/.config/rundev/certs/. Auto-generated PEM files. Regenerated 30 days before expiry.

Installation Prerequisite

• Disk space: ~50 MB for binary and certs directory.
• Internet: Required once for initial install and cert generation. Runtime is offline-capable.

procedure

1. Install run.dev

Input: System with sudo access, internet connection. Steps: a. Run installer: curl -fsSL https://getrun.dev/install.sh | bash. b. Installer displays all proposed system changes (binary location, sudoers rule, port forwarding rules, mkcert setup). c. User confirms or cancels. On success, binary placed at /usr/local/bin/rundev with run.dev symlink. d. Verify: rundev doctor checks ports, certs, /etc/hosts, and privileged helper. Output: Binary in PATH, sudoers rule installed, port forwarding active, mkcert CA registered. Edge cases: If installer fails, rollback is automatic. If mkcert unavailable, fallback to rcgen (self-signed certs, no green padlock).

2. Add a Project

Input: Path to project directory. Steps: a. Open TUI: rundev or rundev up [project]. b. Press a to add a new project. c. Enter project name and root path. d. rundev scans directory for package.json, Cargo.toml, go.mod, manage.py, Gemfile, Procfile, or docker-compose.yml. e. For each detected file, rundev suggests a start command and detects port from: command flags, .env, package.json proxy field, or framework defaults. f. User accepts suggestions or edits manually. g. Config saved to ~/.config/rundev/projects/<name>.yaml. Output: Project YAML file with services block containing path, command, port, subdomain, optional node_version, and optional env dict. Edge cases: If no framework detected, user must supply command and port manually. If port already in use, rundev offers to kill orphan process.

3. Start Services

Input: Project name (optional; if omitted, start all projects). Steps: a. Run rundev up [project] or press s on selected service in TUI. b. rundev spawns each service as a native child process group (POSIX process group for clean shutdown). c. stdout/stderr captured in ring buffer (100 lines max). d. PID persisted to state.json. e. Service marked as "running" in TUI with green status. Output: Services running in background. Accessible via auto-generated domain: [subdomain].my-platform.local (SNI HTTPS) or my-platform.local for root subdomain. Edge cases: If port already in use, rundev detects occupied port, shows occupant PID, offers to kill it. If start command fails immediately, service marked "crashed" within 2 seconds.

4. Monitor Services

Input: None (real-time data from running processes). Steps: a. Open TUI: rundev. Auto-refresh every 2 seconds. b. View each service: status, PID, uptime, CPU%, memory. c. Aggregate "mood" displayed at top: Vibing (😎), Chill (😌), Got the Flu (🤒), Wounded (🤕), Flatlined (💀), Fixing (🔧). d. If a service exits non-zero, crash message shown (e.g., "bro, api is ded. port 4000 is already taken."). Output: Real-time metrics and status per service. Mood emoji reflects aggregate health. Edge cases: If process hangs or zombie process remains, rundev doctor detects and offers cleanup.

5. Handle Service Crash

Input: Crashed service (exit code != 0, or detected port conflict). Steps: a. TUI shows crash message and "press [f] to let me fix it". b. Option 1 (auto-fix): Press f. rundev executes common remedies: kill process on occupied port, run install step (e.g., npm install), restart dependent services, retry start. c. Option 2 (AI diagnosis): Press / to ask Claude about the crash. Claude reads stderr from ring buffer and explains root cause (requires claude_proxy configured and --no-ai not set). d. Option 3 (manual): Press x to stop, inspect logs (press l), fix manually, press s to restart. Output: Service restarted with corrected state, or user guidance on next steps. Edge cases: If Claude proxy unavailable, press / shows "AI not configured". If auto-fix fails, crash persists and user must investigate manually.

6. Access Service via Browser

Input: Running service with domain configured. Steps: a. rundev intercepts DNS via /etc/hosts entry (e.g., 127.0.0.1 api.myapp.local). b. Browser request to https://api.myapp.local hits 127.0.0.1:443. c. Port forwarding rule (pfctl/iptables) redirects 443 → 1112 (localhost only). d. rundev HTTPS proxy reads TLS SNI, loads matching cert from ~/.config/rundev/certs/. e. Proxy looks up route table (domain → subdomain → service → localhost:port). f. Bidirectional TCP proxy forwards traffic to service. g. Browser shows green padlock (mkcert CA-trusted cert) or warning (rcgen self-signed). Output: Service accessible at HTTPS domain in browser. Edge cases: If cert expired or missing, proxy auto-regenerates (30-day pre-expiry window). If SNI mismatch, proxy rejects or serves fallback cert. If service unreachable on target port, proxy returns 502 gateway error.

7. Stop or Pause Services

Input: Service name or "all". Steps: a. Press x to stop selected service or run rundev down [project]. b. rundev sends SIGTERM to process group, waits up to 5 seconds for graceful shutdown. c. If not dead after 5 seconds, sends SIGKILL. d. PID removed from state.json. e. TUI shows service as "stopped". f. Optional: Press p to pause routing only (service still running but domain points to production, or offline). Output: Service stopped or paused. PID cleaned up. Edge cases: If process ignores SIGTERM (rare), SIGKILL forced. If multiple processes in group, all killed.

8. Manage Background Mode

Input: None (TUI running in background). Steps: a. Press q to quit TUI. Services keep running in background. b. PIDs persisted in state.json survive terminal close. c. Reconnect to running services: rundev opens TUI with existing state. d. Press Q to quit and stop all services. Output: Services running without TUI. TUI state recoverable. Edge cases: If system reboots, services do not auto-start (no systemd integration). Restart with rundev up.

9. Update Project Configuration

Input: Modified ~/.config/rundev/projects/<name>.yaml. Steps: a. Edit YAML file directly or use TUI: press a to add/edit. b. Changes applied on next service start (no hot-reload of config; restart service to see changes). c. Node version changes (e.g., node_version: "22") use nvm to switch before running command. Output: Updated config written to disk. Edge cases: If YAML syntax invalid, TUI shows error on load. Revert to last good version.

10. Cleanup and Uninstall

Input: System with run.dev previously installed. Steps: a. Run rundev clean to stop all services and remove /etc/hosts entries. b. Run rundev uninstall to reverse all system changes: remove binary, sudoers rule, port forwarding rules, mkcert CA (optional confirmation). c. Config directory (~/.config/rundev/) left intact (user's choice to remove). Output: System restored to pre-install state. Edge cases: If port forwarding rules partially applied, uninstall cleans up each component independently.

decision points

Install vs. Build from Source

Decision: Does user want convenience or development mode?

• If prebuilt binary: Run curl -fsSL https://getrun.dev/install.sh | bash. Fast, one-liner, auto-setup.
• If source code editing or compilation: Clone https://github.com/danieltamas/run.dev.git, run make install. Slower, requires Rust toolchain.

mkcert vs. rcgen for SSL

Decision: Is mkcert available and CA-trusted desired?

• If mkcert installed: Use it (preferred). Generates CA-trusted certs, green padlock in browser, zero warnings.
• If mkcert not available (e.g., Linux without mkcert binary): Fall back to rcgen. Generates self-signed certs, red warning in browser, but valid for local dev.

AI Features Enabled?

Decision: Does claude_proxy exist in config.yaml and is --no-ai flag absent?

• If yes: AI features available. Press / in TUI to diagnose crashes, ask questions about services. All processing local.
• If no (or --no-ai flag): AI features disabled. Crash messages show generic text, press / returns "AI not configured". All other features work.

Crash Recovery Strategy

Decision: What action when service crashes?

• If user presses f (auto-fix): rundev kills port-occupant, runs install, restarts dependencies, retries service start.
• If user presses / (AI diagnosis): Claude reads stderr, explains root cause (requires proxy).
• If user presses x then manually edits code: User must press s to restart.
• If none of above: Service stays crashed until user intervenes.

Project Detection

Decision: What start command to suggest?

• If package.json found: Suggest npm run dev, npm start, or yarn dev based on scripts in file.
• Else if Cargo.toml found: Suggest cargo run.
• Else if go.mod found: Suggest go run ..
• Else if manage.py found: Suggest python manage.py runserver.
• Else if Gemfile found: Suggest bundle exec rails server.
• Else if Procfile found: Extract each process line as separate service.
• Else if docker-compose.yml found: Extract service commands, run natively (not in Docker).
• Else: User must supply command manually.

Port Conflict Handling

Decision: Is target port already in use?

• If yes, process is known orphan: Offer to kill it. Retry service start.
• If yes, process is active (not orphan): Show occupant PID/name, ask user to free port or choose different port.
• If no: Proceed with service start.

Network Forwarding Setup

Decision: Which OS?

• If macOS: Use pfctl anchor for port forwarding (80 → 1111, 443 → 1112, localhost only).
• If Linux: Use iptables NAT rules scoped to -d 127.0.0.1 (same effect, no other IPs affected).

Certificate Expiry

Decision: Is cert expiring within 30 days?

• If yes: Auto-regenerate cert before expiry. Hot-reload on next TLS handshake (no service restart needed).
• If no: Keep existing cert.

Node Version Switching

Decision: Does service config specify node_version?

• If yes: Use nvm (if installed) to switch to that version before running command.
• If no or nvm not found: Run command with current node version.

Windows / Unsupported Platform

Decision: Is user on Windows native?

• If yes: Show error "run.dev not supported on Windows. Try WSL2 (untested) or Docker Compose."
• If no (macOS/Linux): Proceed.

output contract

Success Criteria

Service Running State

• Service process spawned and PID > 0. Status in TUI shows "running" with green indicator. PID persisted to ~/.config/rundev/state.json.

HTTPS Domain Accessible

• Entry added to /etc/hosts: 127.0.0.1 [subdomain].my-platform.local.
• Browser can resolve domain and connect to https://[subdomain].my-platform.local without certificate error (green padlock if mkcert, warning if rcgen).
• Reverse proxy logs show "SNI: [subdomain].my-platform.local → localhost:[port]".

SSL Certificate Present

• Certificate file exists at ~/.config/rundev/certs/[domain].pem.
• Certificate valid and not expired (or expiry > 30 days).
• mkcert CA registered in system trust store (macOS Keychain, Linux ca-certificates) if mkcert used.

Process Monitoring Active

• CPU% and memory tracked per-PID. TUI updates every 2 seconds.
• Mood emoji reflects aggregate health (Vibing 😎 if all running, Flatlined 💀 if all stopped).

Project Configuration Saved

• File exists at ~/.config/rundev/projects/[name].yaml.
• YAML valid and contains services block with path, command, port, subdomain.

Crash Handling

• On service non-zero exit, TUI shows crash message (e.g., "bro, api is ded. port 4000 is already taken.").
• If auto-fix triggered, service restarted and status updated within 10 seconds.
• If AI diagnosis triggered, Claude response displayed in TUI within 5 seconds (assuming proxy reachable).

Cleanup

• On rundev clean, all /etc/hosts entries removed. All services stopped. state.json cleared.
• On rundev uninstall, binary, sudoers rule, port forwarding rules removed. Config directory remains (user-choice deletion).

Data Format

Project Config YAML

name: my-platform
domain: my-platform.local
services:
  api:
    path: /Users/dan/code/myapp/api
    command: npm run dev
    port: 4000
    subdomain: api
    node_version: "22"         # optional
    env:                       # optional
      NODE_ENV: development
  frontend:
    path: /Users/dan/code/myapp/frontend
    command: npm run dev
    port: 5173
    subdomain: ""

Global Config YAML

claude_proxy: http://localhost:3456/v1   # optional, for AI features

State File JSON

{
  "projects": {
    "my-platform": {
      "services": {
        "api": { "pid": 12345, "status": "running", "started_at": "2026-03-17T10:00:00Z" },
        "frontend": { "pid": 12346, "status": "running", "started_at": "2026-03-17T10:00:01Z" }
      }
    }
  }
}

Certificate Format

• PEM format. File structure: private key + certificate chain. Standard OpenSSL output.

outcome signal

User Knows It Worked

1. TUI Opens: Run rundev or rundev up. Dashboard appears with list of projects and services. No errors.

2. Service Started: Press s or run rundev up [project]. TUI shows service status change from "stopped" to "running" (green indicator). CPU% and memory appear. No "exited" or "crashed" message.

3. Domain Resolves: Open browser. Type https://api.myapp.local (or configured subdomain). Page loads (either green padlock from mkcert or warning from rcgen). If service responds with content, you know reverse proxy works.

4. Port Forwarding Works: Browser can access port 443 via localhost-only forwarding. No "connection refused" or "timeout". Reverse proxy logs (press l) show incoming TLS request with SNI.

5. Multiple Services Coordinated: Run rundev up [project] with 2+ services. TUI shows all running with correct PIDs and ports. Each service accessible at its own domain. No port conflicts.

6. Crash Detected and Reported: Stop a service manually (kill -9 PID). TUI shows crash message within 2 seconds. Mood changes to 🤒 or 💀 depending on how many services are down.

7. Auto-Fix Works: Service crashes. Press f. TUI shows "Fixing 🔧" emoji. Within 10 seconds, service restarts and status returns to "running".

8. AI Diagnosis Works (if enabled): Service crashes. Press /. Claude window opens. Within 5 seconds, Claude explains the error (e.g., "looks like you're missing npm dependencies"). User reads and acts on feedback.

9. Background Mode: Press q to quit TUI. Services keep running (verify with ps aux | grep [service_command]). Run rundev again. Dashboard reappears with same services and PIDs still running.

10. Cleanup Complete: Run rundev clean. All services stop. /etc/hosts entries removed (verify with cat /etc/hosts | grep myapp.local returns empty). state.json cleared.

11. Doctor Check Passes: Run rundev doctor. Output shows "✓ Port 80 forwarding", "✓ Port 443 forwarding", "✓ /etc/hosts helper", "✓ SSL certs", "✓ mkcert CA" (if applicable). No errors.

12. Uninstall Clean: Run rundev uninstall. Binary removed from /usr/local/bin. Sudoers rule removed (verify with sudo -l). Port forwarding rules purged (verify with pfctl -a rundev -s rules on macOS or iptables -L -n on Linux). No system artifacts left.