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

# Setting up a workspace

> The steps a new workspace is walked through, how each one knows it is done, and how invitations and access fit together

A new workspace opens on setup for the person who created it: five steps, in
the order a team needs them. Someone who joins by invitation never sees this
sequence on the way in; see [Joining by invitation](#joining-by-invitation).
Each is marked done because something in the workspace is true, not because
someone clicked Next. Skip any of them; leave and come back, and setup opens at
the first step still undone. A workspace that connected GitHub last week does
not see that step again.

| Step | Done when |
| - | - |
| **Name your workspace** | Someone has named it here. It starts with the name typed when the workspace was created. |
| **Connect GitHub** | The Orchestra app is installed on a GitHub account, or a repository is connected. See [Connect GitHub](https://docs.orchestrahq.ai/connect-github.md). |
| **Connect Linear** (optional) | Linear is connected. See [Linear issue sync](https://docs.orchestrahq.ai/integrations-linear.md). |
| **Invite teammates** | Someone else has joined, or an invitation is waiting. |
| **Install the CLI** | A machine has reported in, or an agent has worked here. |

A step this environment cannot offer says so and never holds setup open: for
example "GitHub is not set up for this Orchestra environment yet."

**The CLI cannot be installed outside the Orchestra team yet.** The step says
exactly that, and names no command, until the CLI is published. Until then,
sessions started in the cloud from an issue still land in the workspace.

Setup is always reachable from **Settings**: the **Setup** row shows how many
steps are done, and the **Name** row renames the workspace.

## Joining by invitation

A teammate who joins from an invitation opens on a welcome page instead, once:
the workspace's name, what the team has already connected (people, GitHub,
Linear), and the few things that are theirs to do. Nothing on it changes the
workspace. **Go to the workspace** moves past it, and the app opens on the
workspace from then on, in that browser.

Who counts as joining comes from their role in the workspace: whoever creates
a workspace is its admin, and an invitation from setup makes a member. Someone
invited as an admin sees setup like its creator, and can skip any step. Setup
stays reachable from **Settings** for everyone, and for a member it says that
the steps are for whoever runs the workspace.

## Names

The name is recorded in Orchestra, with who set it and when, and the
sign-in workspace is given the same name so the workspace menu agrees. If
that second half fails, setup says the menu may show the old name.

## Picture

A workspace can have a picture, shown in the sidebar, the workspace menu and
the workspace picker in place of its initials. There is one picture, and two
places to change it:

* **In Orchestra:** **Settings**, **Name and picture** (the first step of
  setup). Upload a PNG, JPEG, GIF or WebP image up to 5 MB, or remove it.
* **In the workspace menu's Members and settings**, or the sign-in
  provider's own dashboard.

Both change the same picture, which the sign-in workspace keeps, so a change
in either place shows in the other straight away and the two never disagree.
A change made in Orchestra is also recorded, with who made it and when. A
workspace Orchestra has not let in yet cannot change its picture from
Orchestra. Pictures need sign-in, so an Orchestra run without it shows
initials only.

## Invitations and access

While Orchestra is invite only, two things are needed to use a workspace: an
account, and a workspace that Orchestra has let in. They come from different
places, and setup is where they meet.

* **Inviting a teammate from setup** invites them into this workspace, which
  is already let in. They join, and are in. Nothing else is needed.
* **A person invited to sign up who then creates a new workspace** has an
  account, but their new workspace waits until Orchestra lets it in. The workspace picker says
  so before the workspace is created, and the waiting screen says so after.
* **The waiting screen** names which half is missing. Someone who joined a
  workspace by invitation reads that the joining worked and the workspace is
  not let in yet. Someone who created a workspace is told that if a teammate
  invited them, that invitation is the one to open, and any invitation or
  other workspace they already have is listed with **Join** or **Open**.

Letting a workspace in stays an Orchestra decision: accepting an invitation
never admits a new workspace by itself.


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