docs~/start/workspace.md
/esc
~/start/workspace.md
start/workspace.md · 4 min · updated 2026-11-09 · as markdown

# Your workspace

A workspace is where a team's work lives: its projects, issues, members and settings. Its address is part of every link, as in app.rsva.dev/acme/…. Each project in it has a short key, such as ENG, that starts the key of each of its issues: ENG-12. You can be in several workspaces and switch between them from the workspace menu at the top of the sidebar.

Create a workspace

Who may create one: an address let in from the waitlist (once), and the people the server's operator lists. Everyone else sees Join a workspace instead and joins by invite.

Open Create a workspace on the Welcome screen, or Create or join a workspace in the workspace menu. Creating has three steps.

  1. Name. The workspace name, its Address and a Color for its tile. The address is 3 to 32 lower-case letters, digits and hyphens, checked as you type; it cannot be only a number. The address cannot be changed later.
  2. Projects. "Add your first projects." One project, Engineering (ENG), is there to start; Suggested adds Design, Product, Support or Infrastructure. Each project has a name and a key. You can remove them all and add projects later.
  3. Invite. Email addresses, and the role they join with: Member or Admin. "Each person gets an email with a link that works for 7 days." You can skip this.

Press Create workspace. You are its owner. Open takes you in; Workspace settings opens its settings.

What a new workspace contains

  • You, as Owner, and nobody else until invites are accepted.
  • The projects you added. Each starts with five workflow states: Backlog (where new issues start), Todo, In Progress, Done and Cancelled. Todo is marked Only people: agents do not move issues into it.
  • No issues, labels or cycles yet.

Projects

A project has a name, a key and a color. The key is a letter and then up to 11 letters or digits, upper case.

  • New project: the + by the sidebar's Projects heading, the workspace menu, ⌘K, or n p. Type a name; the key is filled in from it and can be changed. The project opens at once with the five default states.
  • Project settings (, in a project, or the project's ⋯ menu): General (name, key, color), Workflow (add, rename, reorder and delete states, and choose where new issues start), Labels, Cycles.
  • Changing a project's key keeps the old one working: links, /browse/OLD-12 and searches by the old key still find its issues.
  • The project's ⋯ menu also has Archived issues and trash, Copy link, Hide from sidebar and Archive project. Archived projects are in the workspace menu under Archived projects, where they can be restored.

By default only admins create projects and change workflow states; any member can manage labels. See "Who can change" below.

Members and roles

Settings › Members lists everyone in the workspace. There are three roles:

Role What it can do
Owner Everything an admin can. Every workspace has one owner, who cannot leave it.
Admin Also changes settings, members and invites.
Member Creates and edits issues in every project, and what Who can change opens to members.

Admins change other members' roles between Member and Admin and remove members. Nobody can change the owner's role.

Who can change, on the same page, sets for labels, states and projects whether "Admins" or "All members" may change them. Only a signed-in admin changes it.

Agents are members too: they work through API tokens and never get more than a member's rights. See Agents.

Invite people

Admins press Invite people in Settings › Members, enter one or more email addresses, choose Invite as Member or Admin, and send.

  • Each address gets an email with its own link. The link works for 7 days.
  • Pending invites lists the open ones, with Resend and Revoke.
  • An address has one live invite per workspace: inviting it again replaces the earlier link. Addresses already in the workspace are skipped.
  • An invite stops working if the admin who sent it is no longer an admin.

The invited person opens the link and signs in with the invited address, which is filled in and fixed. An address without an account gets one at that first sign-in. Someone signed in as another address is offered Sign out and continue as the invited one. A link that no longer works says only "This invite link no longer works".

Invites go to people's email. Agents do not get invites; they get tokens.

Leave a workspace

Leave … at the bottom of the workspace menu. You lose access to its projects at once; your issues and comments stay. This device's copy of the workspace is deleted. Coming back needs a new invite. If it was your last workspace and you have no other invite, you are signed out too.

Workspace settings

Settings › General (g ,) holds the workspace's name and color; admins change them. The address is shown there but cannot be changed.