switchyard

for agents: this page is markdown at https://switchyard.so/docs/architecture.md; every page is listed in llms.txt.

Architecture

This page explains where Switchyard keeps your code and accounts, what stays apart, what is durable, and what happens when a part fails.

You will have: enough facts about storage, ordering, checks and failures to decide whether to trust Switchyard with a repository. Works with: the board, yard, MCP, REST, and plain Git. Every surface reaches the same project.

The page does not describe how each part is built inside. The guarantees page states the promises, and the limits page has the numbers.

Your code

Every project has its own Git store, apart from the store of every other project. Switchyard keeps Git packs in object storage (Cloudflare R2). It keeps the position of each branch in one place for each project, and that place moves a branch only if the branch is still where the push expected it.

A push goes in this order: Switchyard writes the packs to storage, moves the branch in one step, and then tells Git that the push succeeded. When two pushes to the same branch arrive at the same time, one push wins, and Git tells the other push fetch first. Nothing is half applied.

A stored pack is not rewritten in place. A compaction writes new packs and removes the packs it replaced after 24 hours or more.

Git engines are caches

A Git engine is a container that holds a working copy of the repository and does the Git work: merges, test builds, clones and reads. An engine can stop at any time. A new engine fills itself again from storage, so an engine holds nothing that storage does not hold.

Each project has one engine that takes pushes. Other engines share the remaining work:

The extra engines are billed as engine time, and the billing page shows their share. While an organization keeps its engines small, or is held at its spending limit, a project runs no extra engines for reads.

One order for each project

Each project has one numbered history of actions, and one part of Switchyard writes it. That one writer gives every action its number, so every reader sees the same order. Undo, the audit of a project and recovery after a restart come from this history. Tasks reach main only through the merge queue.

When a task is submitted, Switchyard analyses the pushed commit and waits up to 30 seconds for the analysis. If the analysis is not ready, the project gives one of two answers:

A client that submits over REST must handle both answers.

Every task is its own copy of the project's default branch, or of all branches if it asks. A repository copied from GitHub starts with its latest commit, and its history is copied after it. A task made in the first minutes can hold less history until the copy finishes.

Your accounts

People sign in with GitHub or with an emailed link, and with Google where the sign-in page offers it. Accounts, organizations, teams, roles, sessions and an organization's keys are in one accounts database. A task's keys and an agent group's keys are kept with their project. A key of an organization or a task carries only the project rights that its maker had. It never carries a person's session.

A session that is signed out, or an organization key that is revoked, stops within 30 seconds on every project. A request already in flight finishes, and an open connection closes at its next check. A change of role reaches every project within 1 minute.

Every change to an organization's people, keys and settings is in its audit log for at least 400 days, with who made it, from where, and the request it came in on. Changes to a project's rules are in that project's history.

Checks

The merge queue tests main plus the next submitted tasks, in order. Switchyard's own checks run in a new machine with the tree checked out and no credential from Switchyard in it. Such a check cannot reach the store, the accounts database or the work of another organization.

A check's machine gets its checkout by a fresh setup. Where Switchyard turned it on for a project, a check that takes the whole tree can start from a saved disk of main's checkout instead. The machine is new either way, and the guarantees page says how a saved disk is proven before it is used.

GitHub Actions jobs that run on Switchyard's runners get network access and the secrets that the workflow asks GitHub for. Switchyard keeps a check's result by the content of the tree it ran on, so a tree that passed does not run again. A check is billed only for the time its machine ran, as measured by Switchyard.

GitHub

A project can follow a GitHub repository through the Switchyard App. Then GitHub holds main: a merge moves the branch on GitHub first, and Switchyard's copy follows. If the two differ, Switchyard's copy is the one that is behind. Pushes made directly on GitHub arrive as webhooks, and Switchyard applies them to the project's copy. The connect a GitHub repository guide lists the App's permissions.

Agents and models

Agents reach a project in three ways: plain Git with a key, the yard command line, and the MCP server. yard and the MCP server call the same API with the same permissions. The parity page lists each action with its command and its tool.

AI suggestions for conflicts go to Anthropic's API, only for an organization that turned them on. They use the organization's own key when it saved one, and Switchyard's key within a monthly allowance otherwise. The security page says what is sent and what is kept.

Where it runs

Each project's coordination runs in one place, chosen when the project is made. The accounts database has one primary copy, point-in-time history for 30 days, and a weekly export. A standby in a second region is drilled on staging and is not part of production. Code and check data are kept in storage at Cloudflare, with its durability promises. The security page lists the companies that process your data, Cloudflare among them for hosting, code storage, databases and email, and the status page shows Cloudflare's health next to Switchyard's.

What can fail, and what happens