stepaniah/port-light repository overview

⁠Port-Light

A self-hosted dashboard for host port occupancy. It shows host listeners, Docker port mappings, and Compose declarations.

English⁠ · 简体中文⁠

Quick start⁠ · Unraid⁠ · Documentation⁠

⁠Quick start

Image: stepaniah/port-light⁠ (linux/amd64, linux/arm64). Also published to GHCR on tagged releases (ghcr.io/stepaniah/port-light). Pin a version tag or digest for reproducible deployments.

services:
  port-light:
    image: stepaniah/port-light:v0.8.5
    container_name: port-light
    restart: unless-stopped
    ports:
      - "2100:2100"
    volumes:
      - /path/to/your/compose-stacks:/compose:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - ./data:/data
    environment:
      COMPOSE_SCAN_DIR: /compose

mkdir -p data
docker compose up -d

Open http://localhost:2100.

The Docker socket grants Docker API access, including write operations. Use a socket proxy⁠ to restrict access. See the deployment guide⁠ for Unraid, Podman, and reverse proxy setup.

All three scanners are enabled by default. For installations without Docker, set PORT_LIGHT_SCANNERS=listen,compose. Failed scans or stale data produce a warning and suspend port allocation. See troubleshooting⁠.

⁠Features

• Search by port, service, project, process, or bind address; filter and sort results.
• Group Compose ports by project or service and collapse contiguous ranges.
• Review Compose conflicts and generate replacement port mappings.
• Create and manage reservations, filter by expiry, and copy release commands.
• Define named port ranges and check project declarations against them.
• View up to 32 peers in waterfall or tab layouts. Each machine runs its own instance; management actions run on the corresponding instance.
• Check and reserve ports through the CLI, API, or MCP server.
• Configure seven UI languages, themes, port history, webhooks, and Doctor diagnostics.

The dashboard lists occupied and configured ports. Searching for a port number also shows available alternatives:

⁠Local troubleshooting

The troubleshooting workspace suggests checks, shows recent port changes, and saves reports for later comparison. These checks run locally without a model key.

Optional AI assistance uses your own provider and key, configured in Settings → AI. Choose a preset or add a custom OpenAI-compatible API address. Review the selected evidence and confirm each request; the provider bills your key. See troubleshooting and BYOK⁠ for limits, storage and privacy.

⁠Work with an AI assistant

In Settings → Automation, copy the setup prompt into your AI tool. It includes this instance's URL and instructions to install or update the integration and verify the connection. The assistant can then check project ports, reserve them before starting services, and release its claims when the services stop.

For an assistant that can read GitHub, you can also use:

The instance must be reachable from the AI's execution environment. See the AI setup guide⁠ for MCP, CLI + skill, Docker and update details. AI setup and the packaged MCP entry point are available in v0.8.4 and later.

⁠Access control

Set AUTH_USER and AUTH_PASSWORD to enable Basic Auth for the dashboard and API. Use an HTTPS reverse proxy for public deployments.

With Basic Auth or HIDDEN_UNLOCK_PASSWORD enabled, hidden ports require unlocking before API access. Otherwise, hiding a port affects its display only. See SECURITY.md⁠.

⁠Configuration

Most options are also available in Settings and save automatically to /data/port_light.json. Configure timeout, paths, and secrets through environment variables. Set PORT_LIGHT_SETTINGS_SOURCE=env for read-only settings.

Use custom_ports.example.json⁠ as a template for custom port names. Create the file before bind-mounting it.

⁠Data and privacy

Port-Light has no telemetry. Outbound HTTP requests serve configured peer queries, webhooks, and explicitly confirmed BYOK model requests. Webhooks send {event, port}; model requests send the selected sanitized evidence to your configured provider.

Dashboard and API users can read scan results, machine descriptions, and port rules. Configured hubs also receive this data. Compose .env files are used locally for variable substitution. Doctor reports contain sanitized summaries.

Settings, labels, and history are stored in the data volume. port_light.json may contain peer passwords. CLI release credentials use a private local state directory (/data/cli-state in the container). Browser reservation credentials use tab session storage, and copied release commands contain tokens. Protect sensitive information in the data volume, commands, and screenshots.

⁠Documentation

• Port management⁠: grouping, conflicts, reservations, and range rules
• Deployment⁠ and troubleshooting⁠
• CLI⁠, API and MCP⁠; OpenAPI documentation is available at /docs on a running instance
• Architecture⁠ and contributing⁠

⁠Tech stack

• Backend: Python 3.11+ (CI covers 3.11–3.13), FastAPI, Uvicorn
• Frontend: static HTML/CSS/JS
• Image: python:3.12-slim + iproute2

⁠License

MIT⁠ © 2026 StepaniaH

Changelog⁠ · Security⁠ · Contributing⁠ · Ko-fi⁠