Port Keeper is a comprehensive port management tool for developers that helps manage local development ports, prevent conflicts, and collaborate with teams. It offers both CLI and GUI interfaces.

How do I install Port Keeper?

Install Port Keeper globally using npm: npm install -g portkeeper. For GUI support, use: npm install -g portkeeper --include=optional

Yes, Port Keeper is completely free and open-source, released under the MIT license.

Port Keeper - The Best Port Management Tool for Developers

Simplify Your Development Workflow with Intelligent Port Management

Stop wasting time on port conflicts. Port Keeper automatically manages your local development ports, detects conflicts before they happen, and helps your team collaborate seamlessly. Available as both CLI and GUI with full cross-platform support.

Get Started Free Explore Features

100% Free & Open Source

# Install Port Keeper globally
npm install -g portkeeper

# Reserve a port for your project
portman reserve 3000 --name "my-api" --desc "API server"

# Check port status instantly
portman check 3000

# Launch the GUI
portman gui

Why Developers Choose Port Keeper

The Problem

❌ "Port 3000 is already in use" errors
❌ Manually tracking which project uses which port
❌ Team members conflicting on shared ports
❌ Hunting down processes using ports
❌ No visibility into port usage

The Solution

✅ Reserve ports with project metadata
✅ Automatic conflict detection
✅ Team-wide port configuration sharing
✅ One-click process termination
✅ Real-time port usage dashboard

Powerful Features for Modern Development

Everything you need to manage ports like a pro

Smart Port Detection

Automatically detect which ports are in use and identify the processes using them. No more guessing or manual checks.

Port Reservation System

Reserve ports for specific projects with descriptions and tags. Prevent conflicts before they happen.

CLI & GUI Interfaces

Use the powerful CLI for automation or the beautiful desktop GUI for visual management. Your choice.

AI & Automation Ready

Full JSON output support for scripting and AI agent integration. Built for modern DevOps workflows.

Team Collaboration

Export and share port configurations with your team. Keep everyone on the same page.

Lightning Fast

Built with SQLite for instant performance. No external dependencies or slow network calls.

Get Started in 30 Seconds

CLI Only (Lightweight)

npm install -g portkeeper

Perfect for servers and automation

Recommended

CLI + GUI (Full Features)

npm install -g portkeeper --include=optional

Best for local development

Quick Start Guide

Install Port Keeper using npm
Run portman --help to see all commands
Reserve your first port: portman reserve 3000 --name "my-app"
Launch the GUI: portman gui

CLI Documentation

check

Check if a port is free, reserved, or in use

# Check port status
portman check 3000

# JSON output
portman check 3000 --json

reserve

Reserve a port for a project

# Reserve with description
portman reserve 3000 -n "my-api" -d "API server"

# With tags
portman reserve 3000 -n "my-api" -t "backend,prod"

list

List all reserved and in-use ports

# List all ports
portman list

# Filter by status
portman list -s reserved

# Filter by project
portman list -p "api"

release

Release reserved ports

# Release single port
portman release 3000

# Release multiple
portman release 3000 3001 3002

scan

Scan for all active ports

# Scan all ports
portman scan

# JSON output for automation
portman scan --json

request

Request multiple available ports

# Request 3 sequential ports
portman request 3 -n "microservices"

# Request random ports
portman request 5 -n "tests" -r

kill

Kill process using a port

# Kill process on port
portman kill 3000

# Force kill without confirmation
portman kill 3000 -f

export/import

Export and import configurations

# Export to file
portman export -o config.json

# Import from file
portman import config.json

ai

Display AI agent instructions

# Human-readable guide
portman ai

# Machine-readable JSON
portman ai --json

GUI Documentation

Launch the GUI

portman gui

Opens the Port Keeper desktop application

Dashboard View

📊 Dashboard Screenshot

View all reserved ports
Search and filter ports
Quick actions: Check, Release, Kill
Dark/Light theme support

Active Ports Scan

🔍 Scan View Screenshot

Real-time port scanning
Shows process information
Displays reservation details
Kill processes directly

Keyboard Shortcuts

Cmd/Ctrl + N New Reservation

Cmd/Ctrl + R Refresh

Cmd/Ctrl + F Search

Cmd/Ctrl + E Export

Cmd/Ctrl + I Import

Cmd/Ctrl + S Scan Ports

AI Agent Integration

Port Keeper is designed for automation with comprehensive JSON support

Bash Automation

#!/bin/bash
# Check if port is available
STATUS=$(portman check 3000 --json | jq -r '.status')
if [ "$STATUS" = "free" ]; then
  portman reserve 3000 -n "my-app" --json
fi

# Get all ports for a project
PORTS=$(portman list -p "my-app" --json | jq -r '.[].number')
echo "Project ports: $PORTS"

Python Integration

import subprocess
import json

def check_port(port):
    result = subprocess.run(
        ['portman', 'check', str(port), '--json'],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

def request_ports(count, name):
    result = subprocess.run(
        ['portman', 'request', str(count), '-n', name, '--json'],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# Usage
status = check_port(3000)
if status['status'] == 'free':
    ports = request_ports(3, 'my-service')
    print(f"Allocated: {[p['number'] for p in ports['ports']]}")

Node.js Integration

const { exec } = require('child_process');
const util = require('util');
const execPromise = util.promisify(exec);

async function getPorts(project) {
  const { stdout } = await execPromise(
    `portman list -p "${project}" --json`
  );
  return JSON.parse(stdout);
}

async function releaseAll(project) {
  const ports = await getPorts(project);
  const numbers = ports.map(p => p.number).join(' ');
  
  if (numbers) {
    const { stdout } = await execPromise(
      `portman release ${numbers} --json`
    );
    return JSON.parse(stdout);
  }
}

// Usage
releaseAll('old-project').then(console.log);

CI/CD Pipeline

# GitHub Actions Example
- name: Setup Test Ports
  run: |
    # Request ports for testing
    PORTS=$(portman request 5 -n "ci-${{ github.run_id }}" --json)
    echo "TEST_PORTS=$PORTS" >> $GITHUB_ENV
    
- name: Run Tests
  run: npm test
  
- name: Cleanup Ports
  if: always()
  run: |
    # Extract port numbers and release
    NUMBERS=$(echo $TEST_PORTS | jq -r '.ports[].number' | tr '\n' ' ')
    portman release $NUMBERS --json

JSON Response Examples

Check Response

{
  "port": 3000,
  "status": "reserved",
  "projectName": "my-api",
  "description": "API server"
}

List Response

[
  {
    "number": 3000,
    "projectName": "my-api",
    "status": "reserved",
    "reservedAt": "2025-07-26T10:00:00.000Z"
  }
]

Perfect for Every Development Scenario

Microservices Development

Reserve multiple ports for your services with one command:

portman request 5 --name "microservices" --sequential

Team Collaboration

Share port configurations with your team:

portman export team-ports.json
git add team-ports.json && git commit -m "Update ports"

CI/CD Integration

Automate port management in your pipelines:

PORTS=$(portman request 3 --name "ci-test" --json)
# Run tests with reserved ports
portman release $(echo $PORTS | jq -r '.ports[].number')

Tutorials

Getting Started

Install Port Keeper globally
Check if port 3000 is available
Reserve it for your project
Start your development server

npm install -g portkeeper
portman check 3000
portman reserve 3000 -n "my-app" -d "Dev server"
npm run dev

Team Collaboration

Share port configurations with your team:

# Export current setup
portman export -o team-ports.json

# Commit to repo
git add team-ports.json
git commit -m "Add port configuration"

# Team member imports
git pull
portman import team-ports.json

Microservices Setup

Request multiple ports for microservices:

# Request 5 sequential ports
portman request 5 -n "microservices" -d "Service cluster"

# Output:
# Allocated: 3000, 3001, 3002, 3003, 3004

# Use in docker-compose.yml
# service1: ${PORT_3000:-3000}
# service2: ${PORT_3001:-3001}

Development Workflow

Integrate into your development workflow:

// package.json
{
  "scripts": {
    "predev": "portman check 3000 || exit 1",
    "dev": "next dev -p 3000",
    "postdev": "portman release 3000"
  }
}

Best Practices

📝 Naming Convention

Use descriptive project names:

api-server ✅
frontend-dev ✅
test ❌
p1 ❌

🏷️ Use Tags

Tag ports for better organization:

portman reserve 3000 -n "api" -t "backend,prod"
portman reserve 3001 -n "api" -t "backend,dev"

🔄 Auto-Release

Use auto-release for temporary ports:

portman reserve 3000 -n "test-server" -a

📋 Regular Cleanup

Clean up unused reservations:

# List all reserved ports
portman list -s reserved

# Release unused ones
portman release 3000 3001

Loved by Developers Worldwide

"Port Keeper saved our team hours every week. No more port conflicts!"
- Sarah Chen, Full Stack Developer

"The GUI is beautiful and the CLI is powerful. Best of both worlds."
- Mike Johnson, DevOps Engineer

"Finally, a port manager that just works. Essential tool for any developer."
- Emma Davis, Tech Lead

Start Managing Ports Like a Pro

Join thousands of developers who've simplified their workflow with Port Keeper

Install Now - It's Free View on GitHub