Skip to content

README.md

Latest commit

 

History

History
124 lines (94 loc) · 7.19 KB

README.md

File metadata and controls

124 lines (94 loc) · 7.19 KB
Raw

DevHarbor

License: AGPL v3 Platform: macOS PRs welcome

A harbor for your local dev servers. macOS-first desktop app for managing local Node.js projects. Register your apps once, then start/stop/restart them, switch Node versions per project, edit env vars, watch logs, organize them into folders, and see what's running, all without leaving one window.

Think of it like a "Postman for your local dev servers." Everything stays local: no accounts, no cloud, no telemetry.

Website: www.devharbor.app

Highlights

  • Register once, run forever - point DevHarbor at a project (or import a whole folder of repos at once); it detects the package manager, Node version, scripts, and .env files. Monorepos get an offer to create a task per workspace package.
  • Multi-task apps - services start in dependency order with readiness signals (port, log regex, exit, delay) and stop gracefully in reverse - whole process tree, no orphans.
  • The right Node, every time - per-app version resolution across nvm / fnm / Volta / asdf / system, honoring .nvmrc / engines.node.
  • Live in the menubar - see what's running, start/stop apps, and check ports without opening the window; desktop notifications when something crashes.
  • Logs that work like a terminal - xterm rendering with search, a regex filter view, and ⌘⇧F to search across every running app at once. Crash banners pin the last output and call out port conflicts by name.
  • Layered env vars - global → app → task, with .env watching and secret values encrypted at rest (macOS Keychain). Your settings always win over a repo's .env.
  • Keyboard-first - ⌘K palette, folders/tags, dashboard with live CPU/memory, per-app auto-start + launch at login, signed/notarized builds with auto-update.
  • MCP server for coding agents - opt-in, loopback-only HTTP server that lets an AI coding assistant list, add, start, stop, and inspect your apps through DevHarbor instead of spawning npm run dev in a shell it then loses track of. See MCP server.

MCP server

DevHarbor doubles as an MCP server, so a coding agent (Claude Code, Cursor, or anything else that speaks MCP) manages your dev servers through DevHarbor instead of running them in its own shell. Servers an agent starts this way outlive the agent's session, show up in the app like everything else, and get logs, port tracking, readiness checks, and clean shutdown for free. The desktop updates live as the agent works.

22 tools cover the full surface: list, add, update, and remove apps; add and remove tasks; start, stop, and restart apps or individual tasks; read and search logs; inspect ports, run history, and Node versions; read and set env vars; scan a folder for projects to register; and configure readiness probes so the agent can tell "port is open" apart from "actually ready to serve".

Monorepos are first-class: add_app with workspaceTasks: true registers the repo once and creates one task per workspace package (pnpm, yarn, or npm workspaces), each running its own dev script from its own directory. The agent can then start or stop individual services, wire "API before web" ordering with add_task dependencies, give each service its own health probe, and see which detected port belongs to which service.

It is off by default. Turn it on under Settings → MCP server, copy the client config it shows, and drop that into your agent's MCP settings:

{
  "mcpServers": {
    "devharbor": {
      "type": "http",
      "url": "http://127.0.0.1:6872/mcp",
      "headers": { "Authorization": "Bearer <token from Settings>" }
    }
  }
}

Security posture: binds 127.0.0.1 only (not configurable), requires a bearer token by default, validates Host/Origin on every request, masks secret env values in responses, and redacts them from log output. Optional HTTPS with a locally generated certificate for clients that want it. Design and full tool list in specs/07-mcp-server.md.

Install

macOS (Apple Silicon or Intel). From Releases, download DevHarbor-<version>-arm64.dmg for Apple Silicon (M-series) or …-x64.dmg for Intel, open it, and drag DevHarbor to Applications. (Not sure? Apple menu → About This Mac → "Chip" says "Apple" for arm64.)

Releases are signed with a Developer ID and notarized by Apple, so they open normally - no right-click bypass needed.

Contributing

Contributions welcome! Start with CONTRIBUTING.md - it covers dev setup (pnpm install && pnpm dev), the spec-driven workflow, and the PR checklist. Please also read the Code of Conduct. For security issues, see SECURITY.md.

Status

See specs/PROGRESS.md for the build-status matrix - that file is authoritative.

The specs/ folder is the source of truth for this project. See specs/WORKFLOW.md for the rules of the road (read-before / update-before-code, step-back review after every change, etc.).

Where to start

  1. specs/WORKFLOW.md - how we work
  2. specs/PROGRESS.md - what's actually built right now
  3. specs/00-overview.md - problem, goals, non-goals
  4. specs/01-architecture.md - tech stack, process model, IPC
  5. specs/02-data-model.md - SQLite schema and core types (incl. multi-task model)
  6. specs/03-features.md - every feature, with acceptance criteria
  7. specs/04-ui.md - screens, layout, key interactions
  8. specs/05-roadmap.md - phased delivery plan
  9. specs/07-mcp-server.md - the MCP server: tools, transport, security

Stack (as built)

Electron 33 + Vite + React 18 + TypeScript · Tailwind 3 (hand-rolled components; theme via semantic CSS variables driven by the Radix Colors slate scale - same palette family shadcn/ui, Linear, and Vercel use) · Zustand · better-sqlite3 · @homebridge/node-pty-prebuilt-multiarch · @xterm/xterm (+ fit, search, webgl) · chokidar · pidusage · package-manager-detector · cmdk · react-window + anser · electron-builder + electron-updater · Vitest.

See specs/01-architecture.md for the full rationale and specs/PROGRESS.md for current build status.

License

GNU AGPL-3.0 © 2026 Jainath Ponnala

DevHarbor is free and open source. You may use, study, modify, and share it - but if you distribute a modified version, or run a modified version as a network service, you must release your source under the same AGPL-3.0 license. See LICENSE for the full terms.

The name "DevHarbor" and its logo are trademarks and are not covered by the AGPL - see TRADEMARK.md. Forks are welcome, but please ship them under a different name.