BranchKey Platform
The platform is organised around four entities and one repeating loop. This page gives the whole picture in one place; the sub-pages go deeper.
You register as a user, create a tree to hold your work, start a federation on a branch, and connect your learning agents as leaves.
Entity hierarchy
BranchKey organises everything into a simple hierarchy:
User (you)
└── Tree (a project / collection of federations)
└── Branch (one federation: one model + one aggregation algorithm)
└── Leaf (one participating client that trains locally)
Each level owns the ones beneath it. A user can have many trees; a tree many branches; a branch many leaves. See Platform Entities for what each one is and the settings it carries.
The federated learning loop
Once the entities exist, a federation runs the same loop over and over. Each leaf:
- Trains a local model on its own data (which never leaves the machine).
- Uploads its model weights to BranchKey.
- Waits while BranchKey aggregates everyone's weights once enough have arrived.
- Downloads the aggregated model and continues training from it.
That single turn of the loop is one aggregation; a whole training session made of many aggregations is a run. For the conceptual walkthrough see How federated learning works; for the arithmetic of the combine step see Federated averaging, by hand.
Three ways to interact
| Surface | Who uses it | For what |
|---|---|---|
Web dashboard (app.branchkey.com) | Humans | Create trees/branches/leaves, start/pause/stop runs, view metrics |
| REST API (Gateway + Authentication) | Humans / automation | Everything the dashboard does, programmatically. See the API Reference in the navbar |
| Python client library | Leaves (machines) | Upload weights, receive aggregation notifications, download results |
Most people set up entities in the dashboard, then connect their machines as leaves using the client library. See Getting Started.
Runs: start, pause, stop
A branch's run is what the leaves respond to. You control it from the dashboard or API:
start— the federation is active; leaves may upload, and aggregations fire.pause— temporarily halts; leaves wait.stop— ends the current run; starting again begins a new run number.
Leaves only upload successfully while the run is start. Details in
Configuring a branch.
Collaboration
As a user you can share a tree with other users. Invited users can create their own branches and leaves within that shared tree, so multiple people or organisations can contribute to the same federation project while the hierarchy — and each participant's private data — stays intact.
Where to go next
- Platform Entities — Tree, Branch, Leaf in detail
- Configuring a branch — aggregation algorithms and settings
- Per-field aggregation — federated analytics: statistics across every site, without training a model
- Concepts — the ideas, from weights to averaging
- Getting Started — set up your first federation