Skip to main content
On Orchestra Local, each person’s work stays on their own computer. A Local team is how those computers work together: it holds who is on the team, and your sessions, memories and issues travel between you through each repository’s own git remote. Issues are encrypted with a key only your team holds. Memories and sessions are stored there with secrets and personal details removed, not encrypted, so anyone who can read the repository can read them. Pick your track. Most of it happens in the desktop app; the same steps from a terminal are at the end.

Start a team

You are the first one here. Make the team, invite people and share first, which makes the team key.

Join a team

A teammate invited you. Sign in and join in the app’s setup, and the team key arrives from a teammate’s computer.

Start a team

You do this once, as the team’s admin.
  1. Install the desktop app and sign in. See Install the desktop app. Choose Sign in in the title bar.
  2. Make the team. Open the workspace menu at the top of the sidebar and choose Make a team. The page that opens has every step below, in order, and ticks each one off as it is done. Type the team’s name and choose Make team. If you also have a hosted workspace, pick a different name, so nobody on the team picks the wrong one. (People has the same Make team box.)
  3. Invite each teammate. On the same page, or on People, type their email and choose Invite. Use the email address they will sign in with. Send them the Join a team steps too: the page has them ready to copy into a message, with your team’s name in them.
  4. Turn Orchestra on in the repository you will share first. Add it in Settings, This machine. It needs a git remote. Turn on Share with your team for it. That one switch publishes your sessions and memories to the repository’s git, and lets your teammates’ agents ask your computer about the repository (never about a private session). See When a teammate’s agent asks yours.
  5. Share first. Work in the repository with Orchestra on. When a session ends, what it shares is published, and the team key is made on your computer at that first share. There is nothing to create or copy. Git holds only the key’s name and a check value, never the key.
  6. Let your teammates’ computers get the key. Each teammate’s computer asks for it, and yours sends it while both are online, end to end encrypted. Under Team key on People, each repository says whether the key is on your computer, is still on its way, or does not exist yet because nobody has shared there.
You know it worked when the workspace menu at the top of the sidebar shows the team’s name, each person you invited is listed under the invite box on People as Invited until they join, then in the list as Joined, and, after your first share, People says the team key is on your computer.

Join a team

Each teammate does this once. The steps follow the desktop app’s setup, screen by screen.
  1. Install the desktop app. See Install the desktop app. On the first screen, choose Use this Mac (Use this PC on Windows, Use this computer on Linux).
  2. Sign in. Setup asks Were you invited to a team? Choose Sign in, and sign in in your browser with the email address your invitation went to.
  3. Join the team. Setup says You’re invited to and your team’s name. Choose Join with the team’s name. Your teammates see you on People as soon as you join, as Connected. Nothing of yours is shared until you choose a repository for the team. If setup says No invitations for your address, ask the admin to invite the address you signed in with; or open the link in the email from Orchestra, and the team shows up when you come back to the app.
  4. Choose your repositories. On Which repositories should Orchestra save?, pick the shared repository (pull the latest changes first). On the next screen your team is already chosen for it. Turn on Share with your team for it: that publishes your sessions and memories to the repository’s git, and lets your teammates’ agents ask your computer about it (never about a private session). With it off, nothing of yours in that repository reaches the team, either way. What sharing with your team covers, under the switch, opens the details.
  5. Wait for the team key. Setup ends on Welcome to and your team’s name. Under The team key, each repository says whether the key is on your computer or still on its way. It arrives on its own from a teammate’s computer that is online, end to end encrypted, and is checked against the repository’s git before it is kept. There is nothing to paste, and you can go on while it travels. If a teammate’s computer is never online at the same time as yours, they run orchestra memory key show in the repository and hand you the key in person or through a password manager; paste it under Add a key by hand on People.
  6. Open the team. Choose Open with your team’s name. How joining a team works on the same screen opens this section.
Already past setup? Choose Sign in in the title bar, open the link in the email from Orchestra, and the team shows up in the workspace menu within a minute. If you are on more than one Local team, People asks which one this computer uses. You know it worked when the team’s name is in your workspace menu, People on your teammates’ computers lists you as Connected, and, once the key has arrived, People says it is on your computer, with buttons to open the team’s sessions, memories and issues.

The whole setup at a glance

The first four steps are the setup checklist on People, in the same words. It ticks each one off when it is true, shows where the team key stands, and links back here as Team setup guide. The last row is the real test: Sharing means their work has reached your computer. See When a teammate shows up.

When a teammate shows up

A teammate shows up in People, and in the assignee list, as soon as they join the team. You can assign them an issue right away, before they have shared anything. Each person in People has a status and the step that comes next: Your computer reads the team’s member list in the background, so someone who just joined appears within a few minutes. Someone removed from the team stays in People with their past work, and is no longer offered in the assignee list. For a teammate to reach Sharing, three things are needed:
  • the repository has a team key, and you both hold it;
  • they have worked in the repository with Orchestra on, so there is something of theirs to share (sessions are shared when they end);
  • their work has been pushed, and your computer has fetched it. Orchestra fetches on its own, and at once when a teammate’s laptop that is online signals that it pushed.
Only the team’s admin can see the invitations still waiting, in People or with orchestra team invitations. For anyone else the command says that only the admin can see them.

When a teammate’s agent asks yours

Once you share a repository, your teammates’ agents can also ask your computer a question directly, when nothing published answers it. Your computer answers only from the repositories it already shares through git, never from a private session, and the answer cites the events it came from. Nobody turns this on: the yes to sharing you gave for the repository at setup covers it, and a repository you said no to is never answered. orchestra team share off stops it, and orchestra team share list shows what your computer answers. Details are in When a teammate’s agent asks yours.

One person on every computer

In a team, each person is one person, whichever computer their work comes from. Someone who works on a laptop and a desktop shows once in People and once in the assignee list, and an issue assigned to them is theirs on every computer they use. For that, they need to be signed in on each computer, with the address the invitation went to, when their work is shared. A computer that made its team workspace before this version, or while signed out, moves to the person’s team identity the next time Orchestra starts there signed in (after an update, or when the computer restarts). Nothing is lost: the work done before the move stays theirs. Your own work stays on the computer you did it on. Orchestra never takes in work from another computer as yours, so issues you made on another computer of yours do not show up here as your own.

Teammates’ live sessions in the browser

Once your team is connected, open it in the web app with Open in browser under the team in the workspace menu. Its Sessions page shows Live now: the agent sessions running on teammates’ laptops right now, streamed end to end encrypted to your browser, which you can watch and, where a teammate allows it, message. Nothing of them is stored by Orchestra. See Live sessions in the browser.

A new team, before it has a repository

Making a team, or joining one, shares nothing by itself: a team sees only the repositories added to it. Until a repository on your computer is first given a workspace, your computer is one workspace on Local, shared with the team it uses, so a team you just made is empty. Its page in the app says “Night Shift is empty until a repository is added to it” and lists your repositories with a checkbox each. The first box you check asks you to confirm first, because it switches your computer to separate workspaces for good. Personal appears with the work already on your computer, and the repositories you already turned on move to the team your computer shared with, with their last 30 days of sessions copied there. From then on each team sees only its own workspace, and Personal is never shared. A workspace with no repositories says so, with an Add a repository button, rather than showing another workspace’s work.

One repository, several workspaces

A repository can belong to more than one Local workspace: two teams that work in the same repository, or a team and Personal. Check a box for each in Repositories on this computer (the workspace menu, or Settings, This machine), or run orchestra workspaces add <team> in the repository. Every session in the repository then goes to every workspace it belongs to. Each keeps its own copy, and each team shares its copy with its own teammates exactly as it would for a repository on that team alone: they see it live, through git and in their issue sync. The copy in Personal is never shared. Memories written in the repository go to every workspace too, while issues created there go to its first team workspace, so an issue is never split into two that drift apart. Sessions saved before a workspace was added stay where they were, and nothing is copied. The full rules are in Workspaces on your computer.

Two workspaces with the same name

Your Local team and a hosted workspace are separate things, each with its own name and members. If both are called the same, the workspace menu lists two entries with one name. The Local team is the one that says on this device under its name; the hosted one is Cloud. As the admin you can rename the team any time: open the workspace menu and choose Rename, or use Rename on People. Everyone on the team sees the new name.

If something is not right

From a terminal

The same steps with the orchestra command:
orchestra team create and orchestra team invite end by naming this page, and People in the desktop app has a Team setup guide link to it, so it is at hand when you pass the steps on. How sharing works, what is encrypted and who can read it are in Shared memory and sessions through git. Several Local teams on one computer, and Personal, are in Workspaces on your computer.