Install the desktop app

The Orchestra app is the same workspace as the web app, in a window of its own: every session your agents run, Home for what needs you, issues, Knowledge and your teammates. It also sets up Orchestra Local for you, so you never need a terminal to get started. Your sessions and memories stay on your computer, and no account is needed. Sharing sessions with your team through git is free. Sharing memories and the live team features need the Team plan.

What it needs

Your agents can be any of Claude Code, Codex, Gemini CLI, Cursor or OpenCode, installed the usual way. Orchestra needs a free account: the app’s first screen signs you in, or creates the account in your browser. Your sessions and memory still stay on this computer with Orchestra Local. On Windows, the app runs Orchestra Local on Windows itself, as on a Mac. It installs the orchestra command in %USERPROFILE%\.orchestra\bin and adds that folder to your user PATH; Claude Code and Codex sessions you run on Windows, in a terminal or in VS Code, are saved on this computer. Codex asks you to trust a repository’s hooks once: run /hooks in Codex and trust them. Runs started from Orchestra (New session, or a run sent to this computer) start on Windows itself, with no console window, and keep going after you close the app. Your team’s hosted workspace works there too. The Windows installer is not signed yet, so Windows may warn before it runs.

Install

Mac: open Orchestra-mac.dmg, drag Orchestra to Applications, open it from there, and choose Use this Mac. Move it to Applications before you set it up: an app opened straight from the disk image or from Downloads runs from a temporary location. Linux: make the AppImage executable (chmod +x) and run it, or install the .deb with your package manager; then open Orchestra and choose Use this computer. Windows: run Orchestra-windows.exe, open Orchestra, and choose Use this PC. Setup opens by itself the first time.

What setup does

Setup asks one thing at a time, skips what it does not need to ask, and says what stopped it if something does. The first screen asks where your work lives: on this computer, or in Orchestra Cloud, which is by invitation for now. To suggest repositories it looks at which folders your agents’ sessions ran in, on this computer only. It does not read what those sessions said, and nothing is saved until you choose.

1. Installs the orchestra command at ~/.orchestra/bin/orchestra, the same place the command-line installer uses, and adds that folder to your shell’s startup file (~/.zshrc for zsh). Your coding agents’ hooks run this command, so it lives outside the app: moving or updating the app never breaks them. If a newer orchestra is already there, or one you put there yourself, it is left alone. If your terminal already finds another orchestra first, your startup file is not changed.
2. Sets up Orchestra Local: this computer’s identity, the on-device search model, and the background service that answers lookups. None of your work is sent to Orchestra’s servers; the app sends only an anonymous daily count and checks for updates (see Telemetry).
3. Asks whether you were invited to a team. Choose Sign in with the address your invitation went to, and setup says You’re invited to your team, with Join. Working alone? Choose Skip, I work alone. Joining shares nothing by itself; your team is then chosen for the repositories you pick next, and setup ends on the team’s welcome, with where the team key stands. Every step is in Join a team.
4. Turns on saving in the repositories you choose. Sessions in those repositories and their worktrees are saved. Each repository with a git remote shares its finished sessions and memories with your team through git by default; its switch starts on, and you can turn it off there (see Shared memory and sessions through git). Later, People shows whether each repository publishes your sessions, with a button to keep yours on this computer or share them again, and Make private on a session row keeps one session private. Sessions are shared on every plan. Sharing memories needs the Team plan; without it, memories stay on this computer.
5. Brings in earlier sessions. By default, the last 30 days from those repositories, so your first saved session is one you know. They stay on this computer, and they are not summarized. Turn this off on the same screen.
6. Asks how memories are written. With no model key set, and Claude Code or Codex signed in on this computer, you can let Orchestra write memories with that plan: it runs the agent with no tools, at low priority, at most 12 times an hour, on your own usage. It waits for the computer to be idle with no turn running, but never more than 30 seconds. Otherwise add a model key, or choose Not now: sessions are still saved and searchable, and memories wait.

Home then shows your first saved session. With no earlier sessions, it waits for your first one, and it appears the moment that session’s first turn ends. Add repositories later in Settings, This machine, Repositories.

The app and the orchestra command

They are one install. A repository you enable with orchestra enable in a terminal is saved the same way as one you pick in the app, and signing in from the app signs the command in too. A command you install inside WSL2 has its own home folder, so signing in from the app does not sign it in: run orchestra login in your WSL2 terminal as well. Settings, Account, Updates shows the command’s version under Command line tool, with Install or Update when it needs one. Open tabs are kept for each workspace, and on Cloud for each account and each hosted workspace. Signing out, in the app or with orchestra logout, closes that account’s tabs, so the next person to sign in on this computer starts with none.

Switching workspaces

The workspace menu at the top of the sidebar lists every workspace this window can show, in two groups. Under Local are the workspaces on this computer: Personal (once this computer has separate workspaces) and each Local team, each with a line under its name such as “On this device, 3 repositories” or “On this device, no repositories yet”. Under Cloud is each hosted workspace you belong to. Choose one to show it. You stay signed in: one sign-in covers every hosted workspace you are a member of, so there is no need to sign out to switch. The menu reads the list again each time you open it, so a workspace you joined a moment ago shows up. The Workspace menu in the menu bar lists the same workspaces. Switching changes only what this window shows, as the line under the list says: “Switching changes what this window shows. Each repository’s sessions go to every workspace it belongs to.” If you leave a hosted workspace while the window shows it, the window goes back to the workspace you signed in to.

Which workspaces a repository saves to

Repositories on this computer (the app names your system: this Mac, this PC on Windows, this computer on Linux), in the workspace menu and in Settings, This machine, lists each repository you turned on, with a checkbox for each Local workspace: Personal and each Local team. A repository can be in several. Check a box to add the repository to that workspace, or uncheck it to take the repository out, the same as orchestra workspaces add and orchestra workspaces remove. The app says what changed: new sessions go to every workspace checked, sessions saved before stay where they are, and nothing is copied. The last box stays checked, since a repository always saves somewhere. Each team shares its own copy of the repository’s sessions with its teammates; the copy in Personal is never shared. The rules are in Workspaces on your computer. For a repository that syncs to a hosted workspace, see Switching a repository.

A new workspace, and an empty one

Until a repository is added to a workspace, this computer is one workspace on Local: everything on it is shared with the Local team this computer uses, and that team’s row under Local says “On this device, everything on Local for now”. A Local team you make then is empty: its page says “Night Shift is empty until a repository is added to it” and shows the same repository checklist, so you can add one there. The first box you check asks you to confirm before anything changes. It switches this computer to separate workspaces for good: Personal appears with the work already on this computer, and the repositories you already turned on move to the team this computer shared with, with their last 30 days of sessions copied there. Confirm to apply it, or cancel and nothing changes. A workspace with no repositories shows “Night Shift has no repositories yet” and an Add a repository button, never another workspace’s sessions. When the window shows a Local team, the workspace menu also has Team setup guide, which opens Working as a team on Local. An admin renames the workspace the window shows from the same menu, with Rename: a Local team, or a hosted workspace on Cloud. Only the workspace’s admin can rename it.

Your teammates

Sessions lists your teammates’ sessions in the same table as yours, the way Cloud does. Choose Team to see them; Mine shows only your own. Each row shows the agent, the repository, whose session it is and how long ago it moved, and the search, state and agent filters apply to them too. A session a teammate has open right now sits under Running while their agent works, or under Needs you while it waits on them (a question, or at its prompt for their next message). The list updates every few seconds. Choose one to open it in the app, on the same page as your own sessions: its conversation, changes and outcome, read only. To follow it in the terminal and steer their agent, choose Join in terminal: right-click the row, or use the … menu on the session’s page, and a live teammate’s page also has a Join in terminal button. On macOS this opens a Terminal window; on other systems the app shows the command to run. A session that ended moves under Done, and so does one your computer has stopped hearing from, which does not mean it ended. These come over Orchestra’s relay, end to end encrypted, and need the Team plan and a sign-in on Local. In a Local workspace per team, each team’s window shows that team’s sessions, and Personal shows none. Sessions a teammate published to a repository you saved sit under Done, with a small branch mark beside the title (hover it: shared through git). Open one to read it, with its diffs. It is read only. A session that is both running and published shows once, as running. The app reads your team’s git again every few minutes, and when you switch to Team; a line under the filters says when a repository could not be read. Knowledge search shows From teammates: the memories they shared that match, each with a link to the session it came from, once your team’s key is on this computer (see Shared memory and sessions through git). All of it travels through your repositories’ own git remotes, with your own git credentials. Teammates’ sessions are listed on every plan. Their memories need the Team plan: signed out or on Free, From teammates says so and fetches none (see The Team plan). Your teammates’ agents can also ask your computer a question when nothing published answers it. It answers only from the repositories you share, never from a private session, and the answer cites the events it came from. See When a teammate’s agent asks yours.

Form a team on Local

Local keeps your work on your computer. Your Local team is its own team, separate from any hosted workspace you sign in with, with its own name and members. It holds who is on the team and the team’s plan, never your work: sessions, memories and issues go only through your repositories’ git. The workspace menu at the top of the sidebar shows them in two groups: Local lists your Local team (and your other Local workspaces), and Cloud lists your hosted workspace. A team on Local needs the Team plan on the Local team. On Free, People says so, and Orchestra works on your computer alone: nothing is shared or fetched. To get the Team plan, see Pricing. No terminal is needed. The steps below are the short version; the full guide, with what each teammate does and how to check that everyone is connected, is Working as a team on Local.

1. Sign in. Choose Sign in in the title bar, or on People.
2. Make the team (one person, once). On People, type the team’s name and choose Make team. You are its admin. You can rename it any time from the workspace menu or with Rename on People, and everyone on the team sees the new name.
3. Invite people. On People, type a teammate’s email and choose Invite. They get an email from Orchestra with a link to join. Until they join, they are listed under the invite box, where you can withdraw the invitation.
4. Join (each teammate). Open the link in the email, sign up or sign in, then sign in in the app. The team shows up on People within a minute.
5. Create the team key (one person, once). Under Team key on People, choose Create the team key. The key is shown once: choose Copy and share it with each teammate privately, in a password manager, not in chat, email or git. Then choose Use for each repository, which writes key = "<name>" under [share] in .orchestra/config.toml and commits that file alone. Push it so your teammates get it.
6. Add the key (each teammate). Under Team key on People, paste the key a teammate shared with you and choose Add the key. The app then shows what the team has shared in that repository.
7. See your team’s work. Teammates’ live and shared sessions show in Sessions, their memories in Knowledge, and shared issues in Issues.

If you are on more than one Local team, People asks which one this computer uses. Each repository shares through its own git remote, so turn on saving in it first (Settings, This machine). The key stays on each person’s computer, never in git and never on Orchestra’s servers. The same steps from a terminal are in Shared memory and sessions through git. Local and Cloud are a view. The Local and Cloud choices in the workspace menu and in the title bar are one setting, and so is the workspace you choose under each: they change what the window shows, not where your sessions go. Capture beside them says where this computer’s new sessions are saved.

Updates

The app checks for a new version when it opens and every few hours, downloads it in the background, and installs it when you quit. Settings, Account, Updates, Check for updates checks now; Restart to update installs a downloaded one at once. Each update also brings the orchestra command up to the app’s version, unless a newer one is installed.

Remove it

1. Quit Orchestra from the menu bar icon.
2. Drag Orchestra from Applications to the Trash.

This keeps your sessions, memories and the orchestra command. To turn saving off or remove those too, see Turning it off and Where things are.