GitHub - FredrikAhman/portmanager: Beautiful Wes Anderson-themed port monitoring app with real-time scanning, smart sorting, and vintage pastel aesthetics

6 min read Original article ↗

⚓ Port Manager

A beautiful, real-time port monitoring application with a Wes Anderson-inspired aesthetic. Navigate your system's network ports with vintage charm and pastel elegance!

✨ Features

  • 🎨 Wes Anderson Aesthetic - Gorgeous pastel colors, vintage typography, and symmetrical layouts
  • 🔄 Real-time Port Scanning - Fast, efficient cross-platform port monitoring (macOS, Linux, Windows)
  • 🏠 Smart Sorting - Project-related ports highlighted and sorted first with golden badges
  • 📁 Working Directory Display - See exactly where each process is running from
  • 🔭 Animated Scanning Feedback - Beautiful binocular animation with flowing real-time logs
  • 📊 Comprehensive Details - Process name, PID, CPU, memory, user, paths for every port
  • 🔍 Search & Filter - Find ports by number, process name, protocol, state, or directory
  • ⚡ WebSocket Updates - Live updates without page refreshes
  • 🎯 Responsive Design - Perfect on mobile, tablet, and desktop
  • ♿ Accessible - WCAG 2.1 AA compliant with keyboard navigation

📸 Screenshot

Port Manager Dashboard The Harbor Registry - Wes Anderson-themed port monitoring with vintage charm

🚢 Prerequisites

  • Python 3.9+ (Python 3.11 recommended)
  • Docker (optional, for containerized deployment)
  • Elevated permissions may be required for comprehensive port scanning on some systems

🛠️ Installation

Standard Installation

  1. Clone the repository

    git clone <repository-url>
cd portmanager

  2. Create a virtual environment (recommended)

    python -m venv venv

# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

  3. Install dependencies

    pip install -r backend/requirements.txt

  4. Run the backend server

    cd backend
uvicorn main:app --host 127.0.0.1 --port 8000

  5. Open your browser Navigate to http://localhost:8000 to access the Port Manager dashboard.

🐳 Docker Installation

Docker provides an isolated environment and simplifies deployment.

  1. Build and run with Docker Compose

  2. Access the application Navigate to http://localhost:8000 in your browser.

  3. View logs (optional)

    docker-compose logs -f portmanager

  4. Stop the application

Note: When using Docker with host network mode, port scanning will have access to your host machine's network. This is necessary for accurate port detection.

🎯 Usage

Dashboard Overview

Once the application is running, you'll see:

  • Active Ports Table - List of all open ports with their associated services and processes
  • Port Count - Total number of active ports detected
  • Service Status - Real-time status indicators for each port
  • Search Bar - Filter ports by number, service name, or process

Port Information

Each port entry displays:

  • Port Number - The network port (e.g., 8000, 443)
  • Protocol - TCP or UDP
  • Service Name - Common service identifier (e.g., HTTP, HTTPS, SSH)
  • Process - The application using the port
  • PID - Process identifier
  • Status - Connection state

Real-time Updates

The dashboard automatically updates as:

  • New ports are opened
  • Existing ports are closed
  • Service states change

🏗️ Architecture

Port Manager follows a modern client-server architecture:

┌─────────────────┐      WebSocket/HTTP      ┌─────────────────┐
│                 │ ◄─────────────────────── │                 │
│  Frontend       │                          │  Backend        │
│  (HTML/CSS/JS)  │ ──────────────────────► │  (FastAPI)      │
│                 │                          │                 │
└─────────────────┘                          └─────────────────┘
                                                      │
                                                      │ Port Scanning
                                                      ▼
                                             ┌─────────────────┐
                                             │  System Ports   │
                                             │  & Services     │
                                             └─────────────────┘

Backend Components

  • FastAPI Framework - High-performance async web framework
  • WebSocket Server - Real-time bidirectional communication
  • Port Scanner - Efficient system port detection using psutil
  • Service Resolver - Maps ports to common service names
  • Process Monitor - Tracks which applications are using ports

Frontend Components

  • Vanilla JavaScript - No heavy frameworks, fast and responsive
  • WebSocket Client - Maintains persistent connection to backend
  • Dynamic UI - Reactive updates without page reloads
  • Responsive Design - Works on desktop, tablet, and mobile

📡 API Endpoints

HTTP Endpoints

GET /

Returns the main dashboard HTML page.

Response: HTML page

GET /api/ports

Retrieves current list of all active ports.

Response:

{
  "ports": [
    {
      "port": 8000,
      "protocol": "tcp",
      "service": "http-alt",
      "process": "python",
      "pid": 12345,
      "status": "LISTEN"
    }
  ]
}

GET /health

Health check endpoint for monitoring.

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-18T12:00:00Z"
}

WebSocket Endpoint

WS /ws

Establishes WebSocket connection for real-time port updates.

Message Format:

{
  "type": "port_update",
  "data": {
    "ports": [...],
    "timestamp": "2025-10-18T12:00:00Z"
  }
}

Connection Flow:

  1. Client connects to /ws
  2. Server sends initial port list
  3. Server sends updates every 2 seconds (configurable)
  4. Client displays updates in real-time

🖥️ Platform Compatibility

Platform Status Notes
macOS ✅ Fully Supported Best performance on Unix-based systems
Linux ✅ Fully Supported May require sudo for privileged ports
Windows ✅ Supported Run as Administrator for full port access

Platform-Specific Notes

macOS/Linux:

  • Some system ports (1-1024) may require root/sudo access
  • Use sudo uvicorn main:app if you encounter permission errors

Windows:

  • Run Command Prompt or PowerShell as Administrator
  • Windows Firewall may prompt for network access

🔒 Security Considerations

Localhost Binding

By default, Port Manager binds to 127.0.0.1 (localhost only) for security:

  • Only accessible from your local machine
  • Not exposed to external networks
  • Safe for development and personal use

Network Exposure Warning

To expose Port Manager on your network:

  1. Change HOST to 0.0.0.0 in .env
  2. Security Risk: Anyone on your network can access the dashboard
  3. Consider adding authentication if exposing publicly
  4. Use firewall rules to restrict access

Port Scanning Permissions

  • Port scanning may be restricted on some systems
  • Corporate/educational networks may have policies against port scanning
  • Always ensure you have permission to scan the target system

🔧 Configuration

Create a .env file (or copy from .env.example):

# Server Configuration
HOST=127.0.0.1
PORT=8000

# Logging
LOG_LEVEL=info

# Scanning Configuration
SCAN_INTERVAL=2

Configuration Options

  • HOST - IP address to bind server (default: 127.0.0.1)
  • PORT - Port number for the application (default: 8000)
  • LOG_LEVEL - Logging verbosity: debug, info, warning, error (default: info)
  • SCAN_INTERVAL - Seconds between port scans (default: 2)

🐛 Troubleshooting

Port Scanning Returns Empty Results

Problem: No ports detected or limited results

Solutions:

  • Run with elevated permissions: sudo python -m uvicorn main:app
  • Check if security software is blocking the scan
  • Verify psutil is installed: pip install psutil

WebSocket Connection Failed

Problem: Real-time updates not working

Solutions:

  • Check browser console for errors
  • Ensure firewall allows WebSocket connections
  • Verify server is running: curl http://localhost:8000/health

Docker Container Can't Scan Ports

Problem: Container doesn't detect host ports

Solutions:

  • Ensure network_mode: host is set in docker-compose.yml
  • On macOS, host networking has limitations - consider running natively
  • Check container logs: docker-compose logs portmanager

Application Won't Start

Problem: Server fails to start or crashes

Solutions:

  • Check if port 8000 is already in use: lsof -i :8000 (macOS/Linux)
  • Verify Python version: python --version (must be 3.9+)
  • Reinstall dependencies: pip install -r backend/requirements.txt --force-reinstall

Permission Denied Errors

Problem: Access denied when scanning ports

Solutions:

  • Run as administrator/root
  • Check file permissions: chmod +x backend/main.py
  • Disable SELinux temporarily (Linux): sudo setenforce 0

🤝 Contributing

Contributions are welcome! Here's how you can help:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Setup

# Install development dependencies
pip install -r backend/requirements-dev.txt

# Run tests
pytest

# Format code
black backend/
isort backend/

# Lint code
flake8 backend/

Code Style

  • Follow PEP 8 guidelines
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with FastAPI - The modern Python web framework
  • Port detection powered by psutil
  • Inspired by classic network monitoring tools with a modern twist

⚓ Happy Port Managing! 🚢

May your ports be always open and your services forever running.