Introduction
Arbiter local development control plane documentation
Arbiter
Arbiter is a local-first Linux control plane for understanding, diagnosing, and safely operating local development projects, Docker/Compose resources, host processes, ports, files, and multi-service environments.
It strictly adheres to an observe → diagnose → propose → approve → act → verify workflow and binds its REST API to 127.0.0.1 by default.
Quick Start
# 1. Setup environment and install dependencies
cp .env.example .env
uv sync --all-extras
# 2. Start the Arbiter daemon
uv run arbiter serve
# 3. Verify health and port listeners
curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/api/v1/portsOpen http://127.0.0.1:8765 to access the Web Control Panel.
Interfaces & Integrations
Arbiter provides consistent, safety-backed operational capabilities across multiple interfaces:
| Interface / Protocol | Command / Entrypoint | Description |
|---|---|---|
| Web Control Panel | http://127.0.0.1:8765 | Interactive topology canvas, observability, container logs/metrics, approvals, and admin. |
| Terminal UI (TUI) | arbiter tui | Fast, keyboard-driven terminal dashboard (like lazydocker/k9s) with vim navigation. |
| CLI & Fuzzy Pickers | arbiter <command> | fzf-style interactive selectors for projects, ports, containers, and approvals. |
| Shell Prompt Hook | arbiter prompt | Status pills in zsh, bash, fish, or Starship prompts. |
| Model Context Protocol | arbiter mcp | Native stdio MCP server for Claude Desktop, Cursor, Zed, and Antigravity. |
| Agent-to-Agent (A2A) | /.well-known/agent-card.json | Inter-agent discovery and task delegation protocol. |
| REST & Event APIs | /api/v1/* | Standard REST endpoints, SSE activity stream, and NDJSON streaming agent query. |
Core Capabilities
- Live Machine Topology: Real-time relational graph linking projects, Compose files/services, containers, images, volumes, networks, ports, host processes, Dockerfiles, and Make targets.
- Port Conflict Reconciliation: Deterministic port collision detection and automatic free-port reassignment across
.envandcompose.yamlwith backup and rollback. - Multi-Project Stacks: Named environment profiles with 1-click context switching, topological DAG boot ordering (Kahn's algorithm), and multi-probe readiness gates (
tcp_port,http_get,docker_health). - Config & Secrets Intelligence: Proactive detection of port drift and missing
.envvariables compared to.env.example, with zero raw secret exposure and time-travel visual diffs. - Safety Engine: 5-tier risk classification (
READ_ONLYtoDESTRUCTIVE), immutable serialized approval payloads, and independent post-action verification.
Documentation Navigation
- Concepts:
- Architecture & Safety — System domains and design principles.
- Safety & Verification — Risk tiers, approval engine, and rollback compensations.
- Topology Graph — Real-time machine graph and correlation engine.
- Features:
- Multi-Project Stacks — Stacks, DAG boot plans, and readiness gates.
- Config & Secrets Intelligence — Port drift and credential audits.
- Docker & Compose — Container lifecycles, logs, stats, and port editing.
- Config Editor & Make — Safe file editing, Make targets, and Dockerfile diagnostics.
- Interfaces:
- Web Control Panel — Browser console walkthrough and observability tools.
- CLI & Shell Ergonomics — CLI commands, pickers, and Starship prompt setup.
- Terminal UI (TUI) — Full-screen terminal dashboard and keybindings.
- Protocols & Integrations:
- Model Context Protocol (MCP) — Connecting Claude, Cursor, and Zed via stdio MCP.
- Agent-to-Agent (A2A) — Agent Card specification and task delegation.
- AI Agent & Tool Runtime — LangGraph agent, tool loop, and NDJSON streaming.
- Reference & Development:
- Configuration Reference — Complete
.envsettings table. - REST API Reference — Exhaustive REST endpoints and SSE/NDJSON reference.
- Development Guide — Contributing, testing (
pytest/hypothesis), and building.
- Configuration Reference — Complete