Architecture

Switchyard uses a control plane / data plane architecture. This design ensures your source code never leaves your infrastructure while giving you a fully managed orchestration experience.

Control Plane

The control plane runs on Cloudflare Workers at switchyard.cloud. It handles:

• Task orchestration — state machine, dependency resolution, scheduling
• Pipeline management — stage configuration, advancement, auto-scheduling
• Dashboard — task board, analytics, human review queue, settings
• Team management — members, roles, invitations, SSO
• Analytics — cost tracking, performance metrics, utilization

The control plane stores task metadata in Cloudflare D1 databases. It never stores source code, API keys, file contents, or execution trace data.

Data Plane (Relay)

The relay runs on your infrastructure as a Docker container. It manages:

• Git repositories — cloning, pulling, worktree creation
• Agent containers — spawning Claude Code CLI instances for each task
• Execution traces — full dialogue history in local SQLite
• Secrets — API keys encrypted with AES-256-GCM, stored on a persistent Docker volume

Communication

The relay maintains a persistent WebSocket connection to the control plane. Messages flow in both directions:

Control plane → Relay (commands):

• clone_repo, create_worktree, spawn_agent, destroy_agent
• get_trace_content, get_diff, merge_branch

Relay → Control plane (events):

• agent_completed, agent_failed, agent_event
• Task metadata: status, step counts, token usage, costs

All communication carries metadata only. Source code, file contents, and API keys never cross the WebSocket boundary.

Pipeline stages

Each task group flows through configurable pipeline stages:

Stage	Agent Type	Purpose
plan	Planner	Decompose task into subtasks
write_tests	Tester	Write tests before implementation
implement	Coder	Implement the feature
code_review	Reviewer	Review code quality
security_review	Security	Audit for vulnerabilities
merge_decision	Validator	Final merge approval

Stages can run in parallel (e.g., code review and security review simultaneously). Each project can override the default pipeline with custom stages, instructions, model tiers, and timeouts.

Isolation

Every agent task runs in its own git worktree — a lightweight copy of the repository at a specific branch. This provides:

• Filesystem isolation without duplicating the entire repo
• No file conflicts between concurrent agents
• Clean diffs showing exactly what each agent changed
• Easy rollback by removing the worktree