Services & Port Forwarding

Companion services

Services are Docker containers that run alongside your dev environment. They are created on a shared network, so your code can reach them by name.

services:
  - name: postgres
    image: postgres:16
    ports: [5432]
    env:
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: myapp

  - name: redis
    image: redis:7
    ports: [6379]

Inside the container, postgres:5432 and redis:6379 resolve automatically via Docker DNS.

Service lifecycle

Services start when podspawn dev runs and stop when podspawn down runs. If you exit the shell, they stay alive during the grace period (same as the main container).

Port forwarding

Ports listed in ports.expose are forwarded from the container to your host machine.

ports:
  expose: [3000, 8080]
  strategy: auto

Strategies

Forward to the same host port. If the port is already taken, pick the next available and print the mapping.

ports:
  expose: [3000, 8080]
  strategy: auto

Best for local development where you might have multiple projects running. You always get a port, even if your preferred one is busy.

Only forward ports specified via the --ports flag. Ports declared in the Podfile are ignored.

podspawn dev --ports 9090,9091

Useful when you want full control over which ports are exposed, or when running in CI where port mapping is handled externally.

Forward to the exact host port specified. Fail immediately if the port is already in use.

ports:
  expose: [3000, 8080]
  strategy: expose

Use this when your tooling depends on specific ports (hardcoded URLs, OAuth callbacks) and a different port would break things.

Extra ports via flag

Forward additional ports beyond what the Podfile declares:

podspawn dev --ports 9090,9091

These are merged with the Podfile's ports.expose list.

Port conflict resolution

With the auto strategy, if port 3000 is taken on your host (maybe another project is running), podspawn picks the next available port and shows you the mapping:

port conflict, using alternative: wanted=3000 using=3001