devrouter

Local-first routing for macOS development with one shared Traefik router.

What it solves

Run multiple repos concurrently without manual port juggling:

• HTTP apps by hostname: web.localhost, api.localhost
• PostgreSQL DBs by hostname on shared :5432 via TLS/SNI: db.localhost

Traefik owns:

• :80 (HTTP)
• :443 (HTTPS)
• :5432 (Postgres TCP routing)

Unified repo config

Each repo now uses one file:

• .devrouter.yml

This is the only supported per-repo config for app routing/runtime definitions.

Core commands

• dev init [--repo <path>] [--entries-json <json>] [--json]
• dev up
• dev down
• dev status [--repo <path>] [--json]
• dev doctor|verify [--repo <path>] [--json]
• dev ls [--json]
• dev open <name>
• dev tls install
• dev repo init [--repo <path>]
• dev app add ...
• dev app ls [--repo <path>] [--json]
• dev app run <name> [--repo <path>] [--yes]
• dev app rm <name> [--repo <path>]

AI-native onboarding prompt

Generate a ready-to-copy onboarding prompt for an AI agent:

dev init --repo /absolute/path/to/repo

Optional: embed target app entries as JSON:

dev init --repo /absolute/path/to/repo --entries-json '[{"name":"web","host":"web.localhost","protocol":"http","runtime":"host"}]'

JSON mode for machine consumption:

dev init --repo /absolute/path/to/repo --json

Health diagnostics

Run deep checks for global router state and repo configuration:

dev doctor --repo /absolute/path/to/repo

Machine-friendly output:

dev doctor --repo /absolute/path/to/repo --json

dev status now includes readiness hints and next-step commands.

.devrouter.yml example

version: 1
project:
  name: my-repo
apps:
  - name: web
    host: web.localhost
    protocol: http
    runtime: host
    hostRun:
      command: pnpm dev
      cwd: .
      strategy:
        type: auto
        denyPorts: [80, 443, 5432]
        allowPortRange: "1024-65535"
    dependencies:
      - app: db

  - name: db
    host: db.localhost
    protocol: tcp
    tcpProtocol: postgres
    runtime: docker
    docker:
      service: db
      internalPort: 5432
      composeFiles:
        - docker-compose.yml

Notes:

• TCP mode currently supports PostgreSQL first (tcpProtocol: postgres).
• Multi-DB hostname routing on shared :5432 requires TLS/SNI.
• Plaintext Postgres is not supported for multiplexed hostname routing.

Runtime behavior

dev app run <name>:

• reads .devrouter.yml
• prompts to start declared dependencies (or use --yes)
• starts only declared docker dependency services
• fails fast if host-runtime dependencies are configured (start those manually)
• starts host app command for host runtime apps
• generates docker overlay in ~/.config/devrouter/cache/... for docker runtime apps

First onboarding quick path

In a repo that has a host app and a Docker Postgres service:

dev repo init
dev app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd .
dev app add --name db --host db.localhost --protocol tcp --runtime docker --tcp-protocol postgres --service db --port 5432 --compose-file docker-compose.yml
dev app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd . --depends-on db
dev tls install
dev app run web --yes
dev ls

Expected endpoints:

• https://web.localhost
• postgres://db.localhost:5432 (tls required)

Demo workspace (in this repo)

A complete sample repository is included at:

• ./demo

It contains:

• one app running on host (web-host)
• the same app running in Docker (web-docker)
• Postgres in Docker (db)
• ready-to-use .devrouter.yml

Run the end-to-end smoke demo:

pnpm demo:smoke

See details:

• ./demo/README.md

Known limitations (v1)

• Host-runtime dependencies are not auto-started; only Docker dependencies are auto-started.
• TCP routing currently supports PostgreSQL only (tcpProtocol: postgres).
• Shared :5432 hostname multiplexing requires TLS/SNI (sslmode=require or stronger).

Router state

Global managed artifacts remain under:

• ~/.config/devrouter/compose.yml
• ~/.config/devrouter/traefik/traefik.yml
• ~/.config/devrouter/traefik/dynamic/base.yml
• ~/.config/devrouter/traefik/dynamic/host-routes.yml
• ~/.config/devrouter/host-routes-state.json
• ~/.config/devrouter/cache/...
• ~/.config/devrouter/certs/*

Docs

• Setup and bootstrapping: docs/GETTING_STARTED.md
• Onboarding repositories and AI prompt: docs/REPO_ONBOARDING.md
• Agent contributor guide: AGENTS.md
• Demo workspace: ./demo/README.md
• Roadmap: docs/PLAN.md