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:
- Extra engines for clones and reads. Up to 8 more engines serve clones and reads of commits by their id, from the same storage. Their number follows the project's clones and reads: one more a minute while they wait, and one fewer after each 30 minutes in which none is used (about a third busy, or with a clone waiting more than 5 seconds). A push always goes to the project's own engine. An extra engine never lists branches, so no client reads an old list of branches from one.
- Extra engines for builds. Rebuilds of the merge preview and the merge queue's test builds run on engines of their own, apart from the engine that takes pushes.
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:
202withRetry-After: the submit is recorded, and the task enters the merge queue by itself when the analysis is done.503withRetry-After: nothing is submitted. Send the submit again after the wait.
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
- Switchyard restarts. A push that Git accepted keeps its commits. A merge in flight is finished from its record.
- A project's engine stops. Storage is intact. The next request starts an engine that fills itself from storage. The notice of a push that was in flight is sent again until the project records it.
- GitHub does not answer. Merges on a followed repository wait. Tasks keep working on Switchyard's copy, and the merge queue moves main on GitHub when GitHub answers. The status and outages page has the detail.
- The accounts database is slow. Sign-in and session reads have a time limit, and past it they are refused with a reason. Other reads fail with an error; they do not guess.
- A project is deleted. The deletion is scheduled 7 days ahead, and
yard project keepcancels it until then. After the deletion, the project's record and Git data are kept 30 days more, then removed (for a project on our older Git host, its record and refs are kept, not its Git objects). Within those 30 days, write to us and we will try to bring it back.