> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Working as a team on Local

> Start a Local team or join one, see the team key reach each computer on its own, and check that each teammate is really connected, step by step

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](#from-a-terminal).

> [card] [Start a team](#start-a-team)
>
> You are the first one here. Make the team, invite people and share
> first, which makes the team key.

> [card] [Join a team](#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](https://docs.orchestrahq.ai/install-desktop.md). 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](#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](#when-a-teammates-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](https://docs.orchestrahq.ai/install-desktop.md).
   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**.

| Who | Step | You know it worked when |
| - | - | - |
| The person starting the team | **Name your team** | The workspace menu shows its name |
| The person starting the team | **Invite people** | They are listed under the invite box on **People** as **Invited** |
| Each teammate | **People joined** | They show in **People** as **Joined**, and can be assigned issues. Once they sign in on Local, **People** says **Connected** |
| Everyone | **Repository on** | The repository's box for this team is checked in **Repositories on this computer** (the workspace menu, or Settings, This machine) |
| Nobody, it is automatic | Team key (a status line, not a step) | **People** says the team key is on this computer. It is made on the first share and reaches each teammate's computer by itself |
| Everyone | Work in the repository | Teammates show as **Sharing** in **People** |

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).

## 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:

| Status | What it means | What comes next |
| - | - | - |
| **Invited** | An invitation is waiting. Only the team's admin sees these, under the invite box. | They accept the email invitation. |
| **Joined** | They accepted. Nothing of theirs has reached your computer yet. | They sign in to Orchestra Local on their computer. |
| **Connected** | Their computer is connected to the team. | They turn on sharing in a repository and work there. |
| **Sharing** | Something they shared through the repository's git has reached your computer: a session, a memory or an issue. | Nothing. Their work shows in **Sessions**, **Memories** and **Issues**. |

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](https://docs.orchestrahq.ai/shared-memory.md#when-a-teammates-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](https://docs.orchestrahq.ai/live-sessions-web.md).

## 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](https://docs.orchestrahq.ai/shared-memory.md#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

| What you see | Why | What to do |
| - | - | - |
| A teammate is missing from **People** or the assignee list | They have not accepted the invitation yet, or your computer has not read the member list since they did | The admin checks that they show as **Invited**. Once they accept, they appear within a few minutes. |
| A teammate stays at **Connected** | Nothing they shared has reached your computer yet | Check the three things in [When a teammate shows up](#when-a-teammate-shows-up). The usual gap is the team key. |
| A teammate shows up twice in **People** | One of their computers shared while signed out, or runs an older version of Orchestra | They update Orchestra and sign in on that computer with the invited address. After their next share, their work shows under one name. |
| An issue assigned to you does not show under **Assigned to me** | Your computer has not moved to your team identity yet: it was signed out the last time Orchestra started | Sign in with the invited address. The move happens the next time Orchestra starts, after an update or a restart of the computer. |
| **People** says the repository has no team key yet | Nobody has shared there yet | The key is made on the first share. Work in the repository with Orchestra on ([Start a team](#start-a-team), steps 5 and 6). |
| The team never shows up after joining | Signed in with a different email than the invitation's, or not signed in in the app | Sign in with the invited address. The team shows within a minute. |
| The terminal, `orchestra local status` or `orchestra doctor` says **Signed out of Orchestra**, or the app asks you to sign in again | Your sign-in ended, so teammates cannot see or join your sessions from this computer. Your sessions and memories stay on it | Run `orchestra login`, or click **Sign in** in the app: one sign-in serves both. The team connection comes back within seconds. |
| `orchestra doctor` or `orchestra team status` says **Your clock is N minutes off from** a teammate's | Your computer's clock and theirs are more than two minutes apart, so the messages between your two computers are dropped: no live sessions, messages or team map between you | Turn on automatic time (on a Mac: System Settings, General, Date & Time, Set time and date automatically; on Windows: Settings, Time & language, Set time automatically) on whichever computer is wrong. The line goes away once a message gets through, with no restart. |
| `orchestra doctor` says a sign-out **could not reach Orchestra to revoke** a device | You signed out while offline. The key was deleted from your computer at once, so nobody can use it, but your team still lists it | Nothing to do: it is revoked the next time you sign in on that computer, or sooner when Orchestra starts or you run a command while online. |
| There is no invite box on **People** | Only the team's admin invites, and inviting needs the Team plan | Ask the admin. If **People** says sharing needs the Team plan, write to the address it shows. |
| A teammate sees the wrong workspace | They chose the hosted workspace with the same name | Choose the entry that says **on this device**, and rename the team. |
| A teammate's agent says your computer declined its question | Your computer answers only from repositories it shares through git, and this one is not among them: you have not said yes there (sessions share by default, but questions wait for your yes), you said no, its `.orchestra/config.toml` turns sharing off, or a team admin turned it off | `orchestra team share list` names what your computer answers, and the repositories waiting for your yes. Run `orchestra session consent yes` in the repository. |
| Your sessions in a repository never reached your teammates | You said no for that repository, a team admin turned it off, or it is in Personal. Laptops set up before sharing became the default did not publish until someone said yes. | `orchestra local status` or `orchestra doctor` names the reason and the command. Then `orchestra session publish --missed` in the repository publishes your ended sessions that never went out. |
| There is no **Open in browser** on Local | Local has no web app: everything is on your computer | Use the desktop app or the terminal client. |
| **Rename** is missing | Only the team's admin can rename it, and **Personal** has no team to rename | Ask the admin, or switch the workspace menu to the team. |
| A team you just made says it is empty, or your work still shows under the old team | No repository has a workspace yet, so your computer is still one workspace | Add a repository to the team on its page, or in **Repositories on this computer**. See [A new team, before it has a repository](#a-new-team-before-it-has-a-repository). |
| A teammate on another team sees your session too | The repository is in both teams' workspaces on your computer, so each team gets its own copy | That is how a repository in several workspaces works. Uncheck the team in **Repositories on this computer**, or run `orchestra workspaces remove <team>`, to stop new sessions going there. |

## From a terminal

The same steps with the `orchestra` command:

```bash theme={null}
# Start a team (the admin, once)
orchestra team create "Night Shift"
orchestra team invite teammate@example.com
orchestra team rename "Night Shift Labs"

# Join a team (each teammate)
orchestra login
orchestra team invited                 # invitations waiting for you
orchestra team accept <invitation id>  # join; this computer connects to the team at once
orchestra team teams                   # the Local teams you are on

# The team key is made at the first share and sent between computers on its own.
# Only for two computers never online at the same time, by hand:
orchestra memory key show              # on a computer that has it, in the repository
orchestra memory key add -             # on the other, in the repository: paste it

# Which workspaces a repository saves to (run in the repository)
orchestra workspaces                   # where it saves, and every workspace
orchestra workspaces add "Night Shift" # also save to the team
orchestra workspaces remove personal   # stop saving to Personal

# Check
orchestra team invitations             # who has not joined yet (the admin only)
orchestra team share list              # what your computer answers when a teammate's agent asks
orchestra status
```

`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](https://docs.orchestrahq.ai/shared-memory.md). Several Local teams
on one computer, and **Personal**, are in
[Workspaces on your computer](https://docs.orchestrahq.ai/shared-memory.md#workspaces-on-your-computer).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.