Harbor

Note: Harbor is unrelated to the CNCF Harbor container registry.

Why Harbor

See the servers already running on your Mac

Harbor inventories current-user TCP listeners and shows their port, process, command, working folder, HTTP response, and likely framework. Strong evidence maps servers to registered projects; probable duplicate project runs and network-visible binds are flagged while unknown listeners remain visible.

Start a project, not a pile of terminals

Add a folder and review the services Harbor detects. It starts dependencies in order, streams logs, monitors health and resources, and resolves project ports. Before starting another copy, Harbor checks whether the project already has a matching server it can safely reuse.

Give coding agents the same source of truth

Harbor exposes its live project and server state through a loopback-only MCP server. Claude and Codex can inspect local listeners, detect a project, read logs, and operate registered projects. A config created by an agent stays paused until you approve that exact config in Harbor.

Install

Download the app

Download the .dmg from the latest release, open it, and drag Harbor to Applications.

Install with Homebrew

brew install --cask luke-fairbanks/tap/harbor

Production releases are signed by Faba Development and notarized by Apple. Harbor supports macOS 11 Big Sur or later on Apple Silicon and Intel Macs.

Starting with v0.4.0, Harbor checks for signed updates shortly after launch and every six hours. It always asks before installing. You can also check manually from project settings → Harbor updates. Managed project processes remain online while Harbor updates and relaunches.

Quick start

1. Open Harbor and choose Add project, or drag a project folder onto the window.
2. Review the detected services and commands, then choose Add to Harbor.
3. Open the project and choose Start project.
4. Open Local servers to see its ports alongside other listeners already running under your macOS user.

Harbor recognizes common JavaScript frameworks and package managers, Django, FastAPI, Flask, Go, Rails, and static sites. If detection misses, you can import or edit a harbor.json configuration instead.

Conservative by design

• Observation is not ownership. Matching a server to a project does not give Harbor permission to stop it.
• Duplicate prevention favors certainty. Harbor reuses a strongly matched server; ambiguous matches block launch and ask you to inspect them.
• Cleanup is identity-protected. Stop is offered only for isolated, untracked servers. Harbor rechecks PID, process start time, and port before it signals the process, and refuses terminals, IDEs, coding agents, and Harbor itself. “Safe to stop” describes process isolation—not whether the process has unsaved work.
• Agent-written commands require local approval. Approval applies to the exact registered config. Changing it through MCP requires a new approval.
• MCP stays local. The server binds to 127.0.0.1 and uses a new bearer token on every Harbor launch. Its descriptor and Harbor’s app-data directory are owner-only on macOS, and the native bridge verifies listener ownership before forwarding credentials.
• Fix with AI is explicit. When you invoke it, Harbor passes the service command, working path, exit state, and recent logs to your installed Codex or Claude CLI. That data is then handled under the privacy terms of whichever provider Harbor invokes.

What Harbor manages

• Dependency-aware start, stop, restart, and one-click project launch
• Preferred-to-next-free port allocation on IPv4 and IPv6
• ${PORT} and ${services.<name>.port} rewiring between services
• Recognition of commands that pin their own port
• HTTP, TCP, log-pattern, and process-alive readiness checks
• Live logs, CPU, and memory for each managed process group
• Opt-in crash restart with bounded backoff
• Re-adoption of verified Harbor processes that survive an app restart
• A menu-bar popover for common project actions
• Framework-aware project detection and editable harbor.json configs

Local server inventory

The Local servers view scans TCP listeners owned by your current macOS user. It combines process, working-directory, command, port, and bounded HTTP evidence to classify each listener as unknown, matched, Harbor-managed, or eligible for identity-safe cleanup.

Harbor can recognize a strongly matching server on a service’s preferred port before allocating another one. If that process shares a group with a terminal, IDE, Claude, or Codex, Harbor leaves it monitor-only and will not take down the host process.

Connect Claude or Codex

Open AI connections and choose Connect Claude Code, Connect Desktop, or Connect Codex. The guided setup installs Harbor's signed, owner-only native bridge. New client configurations contain only its stable command path: no bearer token, environment variables, Node.js installation, or first-run download is required. If Harbor is closed, the bridge opens it quietly in the background. After connecting for the first time, start a new client session (or fully quit and reopen an already-running client) so it loads the new entry.

The client-owned stdio process stays connected while Harbor quits and reopens. It re-reads Harbor's protected endpoint descriptor, follows token and port rotations, and replays the MCP backend lifecycle before forwarding the next request. Upgrading from Harbor v0.4.2's legacy launcher requires one final client restart; normal Harbor restarts after that do not. A later Harbor update that replaces the bridge binary itself also requires a client restart before the running client can use the new bridge code.

Harbor distinguishes a saved configuration from an observed Bridge running process; the latter means the client launched the bridge, while the client's own MCP tool list is the final confirmation that it accepted the catalog.

Advanced users can connect directly over Streamable HTTP. Read the current port and token from ~/Library/Application Support/com.harbor.desktop/mcp.json; the port can differ from 7777 and the token changes after every Harbor restart.

SETTINGS="$HOME/Library/Application Support/com.harbor.desktop/mcp.json"
PORT="$(plutil -extract port raw -o - "$SETTINGS")"
TOKEN="$(plutil -extract token raw -o - "$SETTINGS")"
claude mcp add harbor --scope user --transport http "http://127.0.0.1:${PORT}/mcp" \
  --header "Authorization: Bearer ${TOKEN}"

Then try:

What local servers are running, and do any look duplicated?

MCP tools

Tool	Purpose
list_apps	List registered projects and their current run status
app_status(app)	Inspect services, resolved ports, and the port plan
detect_app(path)	Scan a folder and propose a config without saving it
register_app(config)	Add or replace a config as approval required
start_app(app, profile?)	Start an approved project or profile
stop_app(app)	Stop Harbor-managed services for a project
restart_app(app, profile?)	Restart an approved project or profile
get_logs(app, service, lines?)	Read recent captured logs
list_local_servers	Inventory listeners, matches, and probable duplicates
stop_local_server(pid, port, startedAt)	Request identity-safe cleanup of an isolated server
open_app(app)	Open a running project’s primary URL

Build from source

Harbor uses Tauri 2 with a Rust core and a React 19 / Radix Themes interface.

npm install
npm run prepare:bridge
npm run tauri dev

Run the local production build without updater artifacts:

npm run tauri:build:local

Verify changes

npm run prepare:bridge
npm test
npm run build
npm run test:rust

cargo fmt --manifest-path src-tauri/Cargo.toml --all -- --check
cargo fmt --manifest-path src-tauri/mcp-bridge/Cargo.toml --all -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --locked --all-targets -- -D warnings
cargo clippy --manifest-path src-tauri/mcp-bridge/Cargo.toml --locked --all-targets -- -D warnings
cargo test --manifest-path src-tauri/mcp-bridge/Cargo.toml --locked

When changing MCP schemas, transport, authentication, or the native bridge, start the patched Harbor build after using one-click setup at least once, then exercise the exact installed Claude/Codex bridge for 90 seconds:

node scripts/mcp-bridge-soak.mjs --restart-harbor --duration-ms 90000 --interval-ms 30000

The harness performs Claude-compatible initialization, validates all advertised tool schemas, and repeatedly calls the read-only list_apps tool. It must end with PASS and no schema, authentication, transport, or reconnect errors.

See DESIGN.md for the shipped architecture, ROADMAP.md for planned work, and DISTRIBUTING.md for the signed release process.

Feedback and contributing

Found a listener Harbor misidentified, a project it could not detect, or an MCP client that would not connect? Open a guided issue. Please remove tokens, credentials, .env contents, and private paths before posting logs or commands.

Issues and pull requests are welcome. Security vulnerabilities should be reported privately through GitHub’s security advisory form.

License

MIT © Luke Fairbanks