> ## 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. # Install the desktop app > The Orchestra app for Mac, Windows and Linux: what it needs, what setting it up changes on your computer, how it works with the orchestra command, updates, and how to remove it 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. > [card] [Mac](https://get.orchestrahq.ai/desktop/Orchestra-mac.dmg) > > One download for Apple Silicon and Intel. > [card] [Windows](https://get.orchestrahq.ai/desktop/Orchestra-windows.exe) > > One installer for x64 and Arm. Signs in to your team's workspace. > [card] [Linux](https://get.orchestrahq.ai/desktop/Orchestra-linux-x86_64.AppImage) > > AppImage for x86-64. Other builds are listed below. ## What it needs | System | Download | Orchestra Local in the app | | - | - | - | | macOS 13 (Ventura) or newer, Apple Silicon or Intel | [Orchestra-mac.dmg](https://get.orchestrahq.ai/desktop/Orchestra-mac.dmg) | Yes | | Linux with glibc, x86-64 | [AppImage](https://get.orchestrahq.ai/desktop/Orchestra-linux-x86_64.AppImage) or [.deb](https://get.orchestrahq.ai/desktop/Orchestra-linux-amd64.deb) | Yes | | Linux with glibc, arm64 | [AppImage](https://get.orchestrahq.ai/desktop/Orchestra-linux-arm64.AppImage) or [.deb](https://get.orchestrahq.ai/desktop/Orchestra-linux-arm64.deb) | Yes | | Windows 10 or 11, x64 or Arm | [Orchestra-windows.exe](https://get.orchestrahq.ai/desktop/Orchestra-windows.exe) | Yes | 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](https://docs.orchestrahq.ai/telemetry.md#every-request-orchestra-makes)). 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](https://docs.orchestrahq.ai/local-teams.md#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](https://docs.orchestrahq.ai/shared-memory.md)). 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](https://docs.orchestrahq.ai/shared-memory.md#workspaces-on-your-computer). For a repository that syncs to a hosted workspace, see [Switching a repository](https://docs.orchestrahq.ai/several-workspaces.md#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](https://docs.orchestrahq.ai/local-teams.md). 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](https://docs.orchestrahq.ai/shared-memory.md)). 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](https://docs.orchestrahq.ai/shared-memory.md#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](https://docs.orchestrahq.ai/shared-memory.md#when-a-teammates-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](https://docs.orchestrahq.ai/pricing.md#how-to-upgrade). 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](https://docs.orchestrahq.ai/local-teams.md). 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 = ""` 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](https://docs.orchestrahq.ai/shared-memory.md). **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](https://docs.orchestrahq.ai/install-cli.md#turning-it-off) and [Where things are](https://docs.orchestrahq.ai/install-cli.md#where-things-are). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.