Switchboard

Real-time agent task coordination with dependency-aware leasing and live-file hosting.

Switchboard is a reference implementation for coordinating multiple agents against a shared task graph. Agents can discover ready work, lease tasks, publish mutable reference files, and observe plan changes without each project needing its own orchestration service.

What It Demonstrates

• Dependency-aware coordination — tasks become available as prerequisites complete.
• Lease-based ownership — agents claim work with expiry and heartbeat semantics that reduce duplicate execution.
• Live state synchronization — plan changes are broadcast to the dashboard and clients over WebSockets.
• Live-file hosting — agents can fetch mutable documents by URL; mutation endpoints can be protected with an admin token.
• Operational visibility — health, readiness, diagnostics, metrics hooks, structured logs, and rate limiting.

Why It Matters

Autonomous coding agents, script runners, and human reviewers need a shared source of truth while work is in flight:

• a plan that changes as tasks complete;
• a queue that respects dependencies and ownership;
• a lightweight document surface for prompts, checklists, and runtime notes;
• a dashboard that exposes coordination state.

Switchboard provides that coordination layer as a small, inspectable application rather than a hosted production service.

Quick Start

1. Set up the environment

# Clone and enter the repository
git clone https://github.com/Nobodyworld/dev-agent-switchboard.git
cd dev-agent-switchboard

# Create a Python 3.11+ virtual environment
python -m venv .venv

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install -r server/requirements-dev.txt

2. Run the server

python scripts/run_uvicorn.py

Open http://localhost:8000/ to view the operator dashboard.

3. Create a task

curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Demo", "description": "Test task"}'

4. Run a demo agent

In another terminal with the virtual environment activated:

python scripts/local_runner.py \
  --base-url http://localhost:8000 \
  --auto-complete \
  --completion-notes "Verified locally"

Watch the dashboard update as work is leased and completed.

5. Review the two-agent flow

See docs/visuals/TWO_AGENT_WORKFLOW.md, then run:

python -m pytest server/tests/test_websocket_plan.py -v

The scenario demonstrates Task A being leased and completed, Task B unlocking, a second agent leasing Task B, and the dashboard receiving live updates.

Validation

Use the current checkout's validation results as the source of truth:

python scripts/dev.py verify
pytest -q
SWITCHBOARD_STRICT_PLAYWRIGHT=1 pytest web/tests/test_ui.py -rA

The latest clean-clone release audit records:

• formatting, lint, type checking, coverage, Bandit, dependency audit, Gitleaks, and link validation passing;
• 229 pytest tests passing with two environment-dependent skips;
• two strict Playwright tests passing;
• 87% aggregate measured coverage;
• one unresolved formal-release blocker: the symlink-containment test must execute on a Linux-capable environment rather than skip under Windows privilege restrictions.

Hosted CI and Commitlint run using SHA-pinned actions. See PUBLIC_RELEASE_AUDIT.md for the exact evidence, current preview disposition, and remaining formal-release gates.

Security Model

The public developer preview is intended for localhost or controlled trusted networks. Public repository visibility makes the source available for review; it does not make a running Switchboard instance safe for public hosting. Untrusted multi-tenant and direct internet-facing deployments are unsupported.

Before using Switchboard on a trusted shared network, review and configure:

Area	Guidance
Admin token	Set SWITCHBOARD_ADMIN_TOKEN for shared deployments. A local demo without a token is not production-safe.
Live-file storage	Keep FILES_ROOT inside the intended storage boundary and validate containment on the target operating system.
Upload limits	Set SWITCHBOARD_MAX_LIVE_FILE_BYTES for the deployment profile.
Network exposure	Keep the preview on localhost or a controlled trusted network; direct public-internet exposure is unsupported.
Secrets	Use environment-specific secret storage and never commit real tokens.
Dependency risk	Run pip-audit, Dependabot, and the documented security gates against any release candidate.

Common settings:

DATABASE_URL=sqlite:///./switchboard.db
STORAGE_ROOT=./storage
FILES_ROOT=./storage/files
SWITCHBOARD_LEASE_SECONDS=60
SWITCHBOARD_ADMIN_TOKEN=replace-with-a-random-secret
SWITCHBOARD_MAX_LIVE_FILE_BYTES=10485760
SWITCHBOARD_RATE_LIMIT_PER_MINUTE=100

See SECURITY.md and docs/configuration.md.

Documentation

• Architecture — components, data flow, and security boundaries.
• API Reference — endpoints and examples.
• Configuration — environment variables and runtime settings.
• Agent Integration — how agents interact with Switchboard.
• Two-Agent Workflow — dependency-unlock sequence.
• Documentation Index — full navigation.

Project Structure

server/                    # FastAPI backend
├── api/                   # REST and WebSocket endpoints
├── application/           # Coordination services
├── domain/                # Task, lease, and dependency models
├── infrastructure/        # Persistence and adapters
├── middleware/            # Rate limiting, logging, observability
└── tests/                 # Server test coverage

client/python/             # Python client library and CLI
web/                       # Operator dashboard and browser tests
scripts/                   # Development, validation, and demo helpers
docs/                      # Architecture, API, integration, and operations docs

Release Status

PUBLIC DEVELOPER PREVIEW — NOT PRODUCTION READY

This classification distinguishes four separate decisions:

1. Repository visibility: the source may be publicly visible for inspection, evaluation, and contribution.
2. Developer-preview availability: developers may run the project locally or on a controlled trusted network.
3. Release authorization: no production release, version tag, or general-availability claim is authorized.
4. Production deployment safety: untrusted multi-tenant and internet-facing deployment remain unsupported.

Formal release authorization remains blocked until the Linux symlink-containment regression executes successfully against the selected release candidate, final clean-clone and Docker evidence is recorded, and the owner completes the release/settings review tracked in issues #95 and #104.

Governance

• Apache License 2.0
• Notice
• Security Policy
• Contributing Guide
• Code of Conduct
• Support Guide

Suggested Reviewer Path

1. Review the dashboard screenshot and architecture diagram.
2. Read the two-agent workflow.
3. Run the quick start locally.
4. Review SECURITY.md and the release audit.
5. Inspect the task, lease, live-file, WebSocket, and browser tests.