PortlerPorts that sort themselves out.

A local development process runner like a small docker compose, but with automatic port assignment and environment resolution.

Getting started

What is Portler?

GitHub

🔌

Automatic port assignment

Portler finds free localhost ports for every service, so two projects (or two worktrees) never fight over port 3000 again.

🔗

Service references

Write backend.url or ${postgres.port} in your env values and Portler resolves them to the assigned addresses at startup.

🐳

Local, Docker, or Kubernetes

The same portler.yml runs services as local processes, in Docker containers, or in a local Kubernetes cluster.

🌐

One project URL

An optional built-in reverse proxy serves your whole stack behind a single origin — no CORS pain, HMR included.

💾

Managed volumes

Project-scoped Docker volumes with one-command forks, made for testing migrations in git worktrees without touching real data.

🚦

Dependency-ordered startup

depends_on plus tcp/http/command healthchecks start services in order and wait until they are actually ready.

Quick taste

portler.ymlterminal

yaml

services:
  postgres:
    image: postgres:16-alpine
    port: 5432
    env:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app

  backend:
    command: npm run dev
    cwd: backend
    port: 4000
    port_env: PORT
    depends_on:
      - postgres
    env:
      DATABASE_URL: postgres://app:app@localhost:${postgres.port}/app

  frontend:
    command: npm run dev
    cwd: frontend
    port: 3000
    port_env: PORT
    env:
      VITE_API_URL: backend.url

bash

$ npm install -g portler
$ portler up

SERVICE    PORT    URL
postgres   51234   http://localhost:51234
backend    51235   http://localhost:51235
frontend   51236   http://localhost:51236

Every service gets a free port, backend.url resolves to the backend's real address, and dependents wait for their dependencies to be ready.