Docs / Mesh setup
Joining a team
Four commands, split across two scopes. Three run once per machine, one runs once per repository — and mixing those two up is the single most common way this goes wrong.
Everything on the main docs page works with no account and no network. This is the part that needs one. For what Mesh is and what it costs, see Flanner Mesh.
Three words first
The console, the CLI and every email Flanner sends use these. They are worth two minutes, because one of them is genuinely not what people assume.
Device
A machine you work on.
It generates its own key the first time it joins, and the private half never leaves it. A device id is the hash of the public half, so nothing assigns it and nobody can issue you one.
Seats are billed per person, not per device. Your laptop and your desktop cost one seat between them, and each still enrols separately because each has its own key.
Workspace
The boundary that decides who sees what.
Not a repository — that is the assumption worth unlearning. One workspace can hold many repositories, and everything inside it syncs as a single set.
So if two repositories share a workspace, anyone with access to that workspace receives plans from both. Splitting them into separate workspaces is the only thing that stops that. Which makes the rule simple: one workspace per group of people who should see the same things, not one per repository.
Most teams want one. They are meant to be coarse — the design allows a hundred per organisation, and ten thousand plans in each.
Entitlement
A short-lived signed note saying which workspaces your device may enter, and with what role.
Your device checks it locally. That is why peers can authorise each other with the control plane unreachable, and why syncing keeps working on a train.
They last a day and renew quietly. It is also why a new grant can take until tomorrow to show up.
Access and binding are different
This is the one that catches people, so it is worth stating plainly.
Access is per person. An admin grants you a role in a workspace. It reaches every machine you have enrolled, and it arrives when your entitlement next renews — up to a day later, or immediately if you run flanner whoami --refresh.
Binding is per repository. Running flanner join inside a repository is what makes review there count for the team. Having access to a workspace binds nothing on its own, and a repository belongs to one workspace at a time.
Put together: you are granted a workspace once, and you join it in each repository you want it to cover.
Once, on the machine you write plans on
An admin invites you by email from the console. That email carries these same steps, so you do not have to keep this page open.
pip install flannerThe client. Same one the free tier uses.
flanner accept <token-from-your-invitation> --as your-handleEnrols this machine and picks your handle. Run it once per machine.
The handle is chosen, not looked up. It is how teammates see you on plans and reviews, and the only rule is that nobody on the team is using it already.
This is typed on that machine on purpose. Joining generates a key there, and the private half never leaves it — not to us, not to your admin. That is why a browser cannot enrol a device for you, and why forwarding the invitation to a colleague enrols their machine rather than yours.
Then, in each repository you share plans from
The first command adopts the repository. The second binds it to a workspace.
flanner initAdopts the repository you are standing in.
flanner join ws_f24dca1f15b391e1Binds that repository to a workspace. Run with no id to list the ones you may use.
Run flanner whoami to see which workspaces you may enter. If it lists none, an admin still has to grant you one, and you will get an email when they do. Running flanner join with no id lists them too.
Syncing with a teammate
Let them reach you, then take their work.
flanner peer serveLets teammates reach this machine. Opens no port and needs no admin rights.
flanner peer pull dev_7ab74afd93b09861Takes their latest work. Syncing is always a pull.
peer serve opens no port and needs no administrator rights. Your machine dials out and answers on that connection, which is why it works from a laptop on hotel wifi.
Open the local web UI and look at its Mesh page for the same facts, with your peers listed.
Your second machine
Same steps, from the top. A seat is a person, not a device, so your desktop and your laptop cost one seat between them. Each still enrols separately, because each generates its own key.