A CLI tool that scans your local ports, detects conflicts against your project’s port assignments, suggests free alternatives, and manages everything through a simple config file.

The Problem

Every developer working on microservices or multiple projects locally has run into this: you start a service and it fails because something else is already using that port. You run lsof -i :3000, kill the process, restart — and repeat this dance daily.

Port conflicts are a constant source of friction in local development, especially on teams where different services claim the same default ports.

How It Works

PortMap gives you full visibility and control over your local port assignments:

Scan — PortMap scans all active ports on your machine, showing which process owns each one with PID, process name, and protocol details.
Detect — Compare what’s actually running against your project’s .portmap.yml config to find conflicts between expected and actual port usage.
Resolve — Find free ports with smart allocation strategies (nearest available, sequential, or random) and update your config automatically.
Monitor — Watch port activity in real-time with a terminal dashboard that updates as services start and stop.

Key Features

Scan active ports and see which process owns each one
Detect conflicts between your config and what’s actually running
Find free ports with smart allocation (nearest, sequential, random)
Live monitoring with a real-time terminal dashboard
Kill processes occupying specific ports
Manage service-to-port mappings via .portmap.yml

Architecture

PortMap is written in Go using the Cobra CLI framework for a clean, discoverable command structure. It reads port information directly from the OS network stack for accuracy and speed.

portmap/
├── cmd/           # CLI commands (scan, check, find, monitor, kill)
├── internal/
│   ├── scanner/   # OS-level port scanning
│   ├── config/    # .portmap.yml parser and manager
│   ├── resolver/  # Free port finder and allocation strategies
│   └── monitor/   # Real-time terminal dashboard
├── pkg/           # Public API for library usage
└── .goreleaser.yml

Releases are automated with GoReleaser and GitHub Actions, producing binaries for Linux, macOS, and Windows.

Installation

# Using Go
go install github.com/ozayartunboran/portmap@latest

# Using Docker
docker run --rm --net=host ghcr.io/ozayartunboran/portmap scan

Quick Start

# Scan all active ports
portmap scan

# Check for conflicts against your config
portmap check

# Find a free port near 3000
portmap find --near 3000

# Start live monitoring dashboard
portmap monitor

# Kill the process on port 8080
portmap kill 8080

Configuration

Create a .portmap.yml in your project root:

services:
  frontend:
    port: 3000
    protocol: tcp
  api:
    port: 8080
    protocol: tcp
  database:
    port: 5432
    protocol: tcp
  redis:
    port: 6379
    protocol: tcp

Then run portmap check to verify no conflicts exist before starting your stack.

PortMap