portman

name	portman
description	Port management for local development with git worktrees. Use when setting up local development environments, booking ports for services to avoid collisions between parallel worktrees, or configuring docker-compose with dynamic ports.
user-invocable	false

Portman Skill

This skill provides patterns for managing port allocations in local development environments using portman. It enables running multiple worktrees of the same project in parallel without port conflicts.

Why Portman?

When working with git worktrees or multiple project instances:

• Each worktree needs unique ports for services (postgres, redis, web server, etc.)
• Manual port management is error-prone and tedious
• Docker-compose files hardcode ports causing conflicts

Portman automatically assigns unique ports per worktree context.

Core Workflow

1. Initial Setup (Once per machine)

# Initialize portman and show shell integration
portman init

# For direnv users (recommended)
portman init --direnv

2. Setting Up a New Worktree

When cloning or creating a new worktree, book ports for all services:

# Auto-discover services from docker-compose.yml
portman book --auto

# Or book specific services
portman book postgres
portman book redis
portman book frontend --port 3000

3. Using Ports in Your Environment

# Export as environment variables (add to .envrc for direnv)
eval "$(portman export --auto)"

# Get a specific port
PGPORT=$(portman get postgres -q)

Command Reference

Command	Description	Example
portman book	Reserve ports for services	portman book --auto
portman get	Get port for a service	portman get postgres -q
portman export	Export as env vars	eval "$(portman export)"
portman status	Show current allocations	portman status --all
portman release	Free port allocations	portman release --all
portman context	Show current context	portman context
portman discover	Preview auto-discovery	portman discover
portman prune	Clean orphaned allocations	portman prune --dry-run

Integration with Docker Compose

Dynamic Port Configuration

Use environment variables in docker-compose.yml:

services:
  postgres:
    image: postgres:16
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    environment:
      POSTGRES_PASSWORD: dev

  redis:
    image: redis:7
    ports:
      - "${REDIS_PORT:-6379}:6379"

  web:
    build: .
    ports:
      - "${WEB_PORT:-8000}:8000"
    environment:
      DATABASE_URL: postgres://localhost:${POSTGRES_PORT:-5432}/app

Direnv Integration (.envrc)

# .envrc - Automatically set ports when entering directory
eval "$(portman export --auto)"

# Or with fallbacks
export POSTGRES_PORT=$(portman get postgres -q 2>/dev/null || echo 5432)
export REDIS_PORT=$(portman get redis -q 2>/dev/null || echo 6379)
export WEB_PORT=$(portman get web -q 2>/dev/null || echo 8000)

Context-Aware Port Allocation

Portman uses the current directory and git remote to create a unique context:

# View your current context
portman context

# Output:
# Context: abc123
# Path: /home/user/projects/myapp-feature-x
# Git Remote: github.com/org/myapp
# Git Branch: feature-x

Each worktree gets its own context, ensuring port isolation.

Port Ranges Configuration

Configure port ranges per service:

# Set custom range for postgres
portman config --set-range postgres:5500-5599

# View current configuration
portman config --show

Maintenance Commands

View All Allocations

# Show current context only
portman status

# Show all contexts
portman status --all

# Check if ports are actually listening
portman status --all --live

Cleanup Orphaned Allocations

# Preview what would be removed
portman prune --dry-run

# Remove allocations for deleted worktrees
portman prune

# Also remove stale allocations (not accessed in 30 days)
portman prune --stale 30

Common Patterns

Setup Script for New Developers

#!/bin/bash
# scripts/dev-setup.sh

# Book ports for all services
portman book --auto

# Show allocated ports
portman status

# Export for current shell
eval "$(portman export --auto)"

echo "Development environment ready!"
echo "PostgreSQL: localhost:$POSTGRES_PORT"
echo "Redis: localhost:$REDIS_PORT"

Makefile Integration

.PHONY: setup ports

setup:
	portman book --auto
	@echo "Ports allocated. Run 'make ports' to see them."

ports:
	@portman status

start:
	eval "$$(portman export --auto)" && docker-compose up

CI/CD Considerations

In CI environments, portman context is unique per workspace, allowing parallel CI jobs:

# GitHub Actions
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup ports
        run: |
          portman book --auto
          eval "$(portman export --auto)"
      - name: Run tests
        run: docker-compose up -d && pytest

Troubleshooting

Port Already in Use

# Check what's using a port
portman status --all --live

# Release and rebook
portman release postgres
portman book postgres

Reset All Allocations

# Release all for current context
portman release --all

# Rebook
portman book --auto