Docs / Setup guide
Setup guide
Join a team, in order.
Three commands run once per machine. One runs once per repository. Keep those two scopes apart and setup takes a few minutes.
Everything else in these docs works without an account. Flanner Mesh needs one. For what it is and what it costs, see Flanner Mesh.
Three terms
The console, the CLI and Flanner's emails use these three terms. One of them does not mean what most people assume.
Device
A machine you work on.
Each device generates its own key when it enrols. The private key never leaves the machine. The device ID is a hash of the public key.
Seats are billed per person, not per device. Your laptop and desktop share one seat. Each still enrols separately, because each has its own key.
Workspace
The boundary that decides who sees what.
A workspace is not a repository. One workspace can hold many repositories, and everything inside it syncs as a single set.
If two repositories share a workspace, anyone with access to it receives plans from both. Use one workspace per group of people who should see the same things, not one per repository.
Most teams need one. Workspaces are meant to be coarse.
Entitlement
A short-lived signed note saying which workspaces your device may enter, and with what role.
Your device checks it locally, so peers can authorise each other while offline.
Entitlements last a day and renew automatically. A new grant can take up to a day to arrive, or run flanner whoami --refresh.
Access and binding are different
These are separate steps, and mixing them up is the most common setup problem.
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.
You are granted a workspace once. You join it in each repository you want it to cover.
Set up the team
Skip this section if you received an invitation.
pip install flannerThe client. Same one everybody runs; nothing about it is admin-only.
flanner login <enrollment-code>Enrols this machine with the code from your console. The first command in this guide that talks to us at all.
flanner invite teammate@company.comSends them an invitation. A seat is charged when somebody accepts, so inviting five people and having two join costs two.
flanner membersWho is on the team, and the seat count you are paying for.
An admin can invite people, revoke machines and manage the subscription. Being an admin does not grant access to any workspace. Creating a workspace gives you a role in it; for other workspaces, grant yourself one from the console.
Then continue with the sections below. The remaining steps are the same for admins and members.
Enrol a machine
Your invitation email contains these steps. If you set up the team yourself, you are already enrolled; skip to the next section.
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, not once per repository.
flanner whoamiWhat this device is entitled to and which workspaces you may enter. Worth running once, so a later refusal is not a surprise.
Choose any handle not already used on your team. Teammates see it on plans and reviews.
Run this on the machine itself. Enrolling generates a key on that machine, and the private key never leaves it. Forwarding the invitation to someone else would enrol their machine, not yours.
Bind a repository
Run these in each repository you want to sync. The first adopts the repository; the second binds it to a workspace.
flanner init --syncAdopts the repository you are standing in, and imports the plan files already in it. Without --sync it adopts the repo and lists nothing, which reads as broken.
flanner join ws_f24dca1f15b391e1Binds that repository to a workspace. Run with no id to list the ones you may use.
flanner whoami lists the workspaces you can join. If it lists none, an admin has not granted you one yet; you will get an email when they do.
Sync with a teammate
Start serving, then pull from a teammate.
flanner peer startLets teammates reach this machine, and keeps doing it after you close the terminal. Opens no port and needs no admin rights. `flanner peer stop` ends it.
flanner peer statusHow this device is reachable, and whether a connection is direct or relayed.
flanner peer pull dev_7ab74afd93b09861Takes their latest work. Syncing is always a pull: nobody puts anything on your machine without you asking.
Serving opens no port and needs no administrator rights. Your machine dials out and answers on that connection, so it works behind routers and firewalls.
peer serve runs in the foreground and stops when you close the terminal. peer start runs in the background. Use start so teammates can pull from you after you close the terminal.
The Mesh page in the local web UI shows the same information, with your peers listed.
Private network
Optional. Most teams do not need this.
flanner mesh connectPuts this device on the team's private network, if your admin set one up. Most teams need nothing here: peers already reach each other by key.
flanner mesh statusWhether this device is on that network. `flanner mesh leave` comes off it.
flanner join binds a repository to a workspace and decides what syncs. flanner mesh connect puts a device on a private network and decides how it is reached.
Devices find each other by public key over the internet. Use a private network only if your team's policy requires it.
Share a memory
Memory does not sync automatically. Share one memory at a time.
flanner mem share mem_9c1f0aOffers one memory to the workspace this repository joined. Always by hand, never as a side effect.
flanner mem withdraw mem_9c1f0aAsks every device to stop recalling it. A request peers honour, not an erasure.
Joining a workspace does not share any existing memories. Each memory is shared by the person who wrote it, when they choose to.
A shared memory is signed by the machine that wrote it. The receiving device verifies the signature, runs the same secret check it runs on local memories, and stores it as a workspace memory marked as received.
Withdrawing asks every device to stop recalling the memory. It does not delete the file from a device that already received it. Personal memory cannot be shared.
An admin can turn memory sharing off for the whole organisation from the console. This stops new sharing. It does not remove memories a device has already received.
Add a second machine
Repeat the steps above on the new machine. A seat is per person, so a second machine costs nothing extra. Each machine enrols separately because each has its own key.