Switchyard Docs
Give each AI agent worktree its own local HTTP runtime: ports, URLs, logs, and agent-readable status without a cloud control plane.
Start with switchyard brief --json for runtime context, or install the MCP
server with switchyard mcp install for agent-native workflows.
API Reference CLI commands, JSON envelopes, MCP resources/tools, config, env vars, and state.
Agent Interface The expected agent workflow: brief first, focused logs, explicit local mutations.
Architecture The small pieces: CLI, config, registry, process runner, proxy, and adapter boundaries.
Why It Helps
Switchyard is for the awkward middle layer between git worktrees and local servers. It gives each branch a discoverable runtime: stable local URLs, allocated ports, logs, JSON state, and MCP resources that agents can inspect without guessing which terminal started what.
Fast Start
brew install pipx
pipx ensurepath
pipx install switchyard-dev
cd your-project
switchyard init --dry-run
switchyard init
switchyard mcp install
Restart your terminal after pipx ensurepath if switchyard is not found.
Without Homebrew, install pipx with python3 -m pip install --user pipx, then
run python3 -m pipx ensurepath.
- 1. Create `switchyard.toml` with `switchyard init`.
- 2. Create a branch worktree with `switchyard create`.
- 3. Start services with `switchyard up`.
- 4. Let agents read `switchyard://project/brief`.
From a project with switchyard.toml, agents should start with:
switchyard brief --json
switchyard mcp smoke --json