Portus

Solo Developer · 2025

A Rust daemon that brokers port allocations atomically, preventing collisions between dev servers and AI coding agents via lease-based IPC and an MCP server.

The Problem

Every dev machine has the same fight: multiple services all want port 3000, and whoever starts last loses. It gets worse when AI coding agents like Claude Code and Cursor spin up parallel workspaces that each try to bind the same ports, causing cascading failures that are hard to diagnose and annoying to fix manually.

Role & Constraints

Solo Developer

• Must be zero-config — daemon auto-starts on first CLI use
• Must handle concurrent allocation requests atomically
• Must recover gracefully from crashes via lease expiry
• Must work cross-platform (macOS, Linux, Windows)
• Must integrate with AI agents via MCP protocol

Approach

Built a background daemon that brokers port allocations atomically. Every service asks Portus for a port before binding. Portus checks availability, records a time-bounded lease, and hands back a guaranteed-unique port. Designed a length-prefixed JSON IPC protocol over Unix sockets for the CLI-to-daemon communication. Added an MCP server so AI agents get native port allocation without any manual coordination. Built a TUI dashboard for real-time monitoring of allocations and listeners.

Media

┌────────────┐ ┌────────────┐ ┌────────────┐
│ Dev Server │ │ AI Agent   │ │ TUI        │
│ (portus    │ │ (MCP       │ │ Dashboard  │
│  request)  │ │  client)   │ │            │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
      │              │               │
      └──────┬───────┘──────┬────────┘
             │              │
    ┌────────▼───────┐ ┌────▼──────────┐
    │ Unix Socket   │ │ MCP Server    │
    │ IPC (JSON)    │ │ (5 tools)     │
    └────────┬──────┘ └────┬───────────┘
             │             │
        ┌────▼─────────────▼────┐
        │   Portus Daemon       │
        │   ┌────────────────┐  │
        │   │ Port Registry  │  │
        │   │ (Lease-based)  │  │
        │   └────────────────┘  │
        │   ┌────────────────┐  │
        │   │ Crash Recovery │  │
        │   │ (Persisted)    │  │
        │   └────────────────┘  │
        └───────────────────────┘

Outcomes

• Shipped a complete CLI with request, release, confirm, list, scan, kill, run, and dashboard commands
• Built an MCP server exposing 5 tools for native AI agent integration
• Implemented lease-based allocation with auto-expiry and crash recovery via persisted registry
• Built a TUI dashboard for real-time port allocation monitoring
• Designed signal-safe cleanup ensuring leases release on SIGTERM/SIGINT

Proof

Reflection

Portus came from a real pain point I hit while using AI coding agents. The problem is simple but the solution touches systems programming fundamentals: IPC design, concurrent state management, crash recovery, and cross-platform compatibility. Building the MCP server integration was particularly interesting because it required thinking about how AI agents interact with system resources differently from human developers.