mdev

mdev

Run several git worktrees as live dev sandboxes in parallel. Each sandbox gets its own workloads and backing services, routed through a single reverse proxy, with no per-sandbox host ports to manage.

• Workloads are the processes you develop (run:). Each declares the ports: it listens on and is served at http://<name>-<port>.<sandbox>.localhost.
• Backing services (postgres, redis, or any container) come from your docker-compose files. mdev runs them with docker compose up --wait and routes every exposed port at http://<service>-<port>.<sandbox>.localhost — the same scheme as workloads.

flowchart LR
  browser -->|"http://api-8000.dev.localhost"| proxy
  proxy <-->|tunnel| agent
  subgraph host ["host · mdev daemon"]
    proxy[reverse proxy]
  end
  subgraph sandbox
    agent[mdev supervisor]
    agent --> workloads[workloads]
    agent --> services[(compose services)]
  end

Install

Prebuilt binaries for Linux and macOS are on the releases page. Or build with Go:

go install github.com/stupside/mdev@latest

Quick start

Daemon config at ~/.config/mdev/config.yml — only the token is required; the listen addresses default to :80 (http) and :14434 (admin):

daemon:
  token: <openssl rand -hex 16>
  listen: { http: ":80", admin: ":14434" }   # optional; these are the defaults

mdev.yaml in your project:

workloads:
  api: { run: bun run apps/api/serve.ts, ports: [8000], env: { DATABASE_URL: postgres://app:dev@postgres:5432/app } }
  web: { run: bun run apps/web/serve.ts, ports: [8080] }

sandboxes:
  dev:
    image: oven/bun:1     # toolchain image for process workloads
    workloads: [api, web]
    runtime:
      docker:
        compose: [docker-compose.yml]  # backing services

Run it:

mdev daemon                                       # host daemon (proxy + tunnel + MCP)
mdev up dev --worktree /path/to/worktree   # spawn a sandbox; Ctrl+C tears it down

Open http://api-8000.dev.localhost. Spin up more worktrees in parallel; still no host ports.

Each sandbox picks its backend with a runtime: block: Docker (default) or Kubernetes. Workloads and URLs are the same either way. See the usage guide for the full reference.

MCP

The daemon serves sandbox-control tools over HTTP at /mcp-admin on the admin port, authenticated with the daemon.token bearer token. Register it with Claude Code:

claude mcp add --transport http mdev \
  http://localhost:14434/mcp-admin \
  --header "Authorization: Bearer <your daemon.token>"

An installable agent skill drives these tools:

npx skills add stupside/mdev

Links

• Usage guide — full configuration reference.
• Examples — runnable sandbox configs.
• Contributing — building, testing, and releasing.
• Design notes — architecture and cloud-agent guidance.

License

MIT