control-plane

An open-source company-layer dashboard for your AI-agent fleet.

control-plane is the persistent dashboard above your AI coding agents. If you run agents in waves with session-orchestrator, each repo gets a local .orchestrator/session.lock lease while a session is live. control-plane reads those leases across every repo and every machine and shows you, in one place, what is actually running right now.

It is the missing top-down view: instead of a session being something you can only see from inside one repo, you get a single board for the whole portfolio.

control-plane is complementary software to session-orchestrator — the orchestrator is the worker (it runs the waves), control-plane is the dashboard (it watches the fleet). You can use the orchestrator without it; control-plane only becomes useful once you have sessions to watch.

---

Feature: Portfolio Session Board

The first shipped feature. A read-only, live board of every session-orchestrator session across your repos.

• Scans each repo under a configured root for .orchestrator/session.lock (the lease session-orchestrator writes for an active session).
• Classifies every session as live or stale based on the lease's last_heartbeat vs. its ttl_hours.
• Groups by host, so sessions spread across multiple machines show up together in one view.
• Polls every few seconds — no websockets, no database, no writes. Pure read-only filesystem inspection.

What you see per session: repo, branch, host, last heartbeat (age), PID, and a live/stale dot.

API

GET /api/portfolio/sessions  ->  PortfolioSnapshot

Returns { generatedAt, root, liveCount, staleCount, hosts[], sessions[] }.

---

Quickstart

Requirements: Node 20+ and pnpm.

pnpm install

# 1. API server — Express on http://localhost:3100
pnpm dev:server

# 2. UI — Vite on http://localhost:5173 (proxies /api -> :3100)
pnpm dev:ui

Then open http://localhost:5173 and pick Portfolio in the sidebar to reach the session board.

Configuration

Env var	Default	Purpose
PORTFOLIO_ROOT	current working directory	Directory whose immediate subdirectories are scanned for repos with .orchestrator/session.lock.
PORT	3100	API server port.

Point PORTFOLIO_ROOT at the parent folder that holds your repos, e.g.:

PORTFOLIO_ROOT=/path/to/your/projects pnpm dev:server

The board is empty until at least one repo under that root has a live session-orchestrator lease.

---

Fork of Paperclip (MIT)

control-plane is a fork of paperclipai/paperclip, an MIT-licensed Node.js + React agent dashboard. We kept its application shell and added the Portfolio Session Board (and the session-orchestrator integration) as new, additive modules so the fork stays easy to rebase against upstream.

This is an independent fork. It is not affiliated with or endorsed by Paperclip AI. See NOTICE for full attribution.

---

Contributing

Contributions are welcome, especially around session-orchestrator integration.

• Open an issue describing the change before large PRs.

• Keep new functionality in new files where possible (the fork rule: add, don't edit) so upstream rebases stay cheap.

• Run the quality gates before opening a PR:

  pnpm typecheck
  pnpm lint
  pnpm test

By contributing you agree your contributions are licensed under the project's MIT License.

---

License

MIT — see LICENSE.

• Original work © 2025 Paperclip AI.
• Modifications and additions © 2026 Bernhard Götzendorfer.