# Teams & members
URL: https://openship.io/docs/guides/teams-members.md

Invite other people into your Openship workspace, give them the right role, and understand the difference between your personal space and a shared team.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Openship starts out as a space for one person: you. But most real work happens with other people —
a teammate who deploys the app, a designer who just needs to look, a co-founder who owns the whole
thing with you. This guide shows how to bring people in and decide what each of them can do.

Think of your workspace like a shared office. You can hand someone a key (invite them), and each key
opens different doors (their **role**). Some keys open everything; some only open one room.

<Callout title="What you need first">
- An Openship account with a workspace you can see in the dashboard.
- The **email address** of the person you want to invite.
- You must be the **owner** or an **admin** of the workspace to invite people. (More on roles below.)
</Callout>

## Invite someone

If you use Desktop locally, open **Settings → Instance → Move to a server** first.
Choose **Use through Desktop** for an API-only installation, or **Desktop + browser**
to publish the dashboard too. Desktop stays connected to the same remote data,
and invitations and webhooks use that server while your computer is offline.
See [Move your control plane](/docs/guides/migrate-control-plane).

For an API-only instance, the invitation page explains how to open Desktop and
paste the invitation link into **Settings → Instance → More instance options → Connect to an instance**.
The recipient signs in with their own account, accepts the invitation, and joins
the team with their assigned role. The team appears in the organization switcher.

<Steps>

<Step>

### Open the Team settings

In the dashboard, go to **Settings** and choose the **Team** tab from the sidebar. This page lists
everyone who currently has access, plus any invitations that haven't been accepted yet.

</Step>

<Step>

### Press "Invite member"

Click **Invite member** in the top-right. An inline **Invite a member** panel expands on the page.

<Callout title="Don't see the button?" type="info">
Only owners and admins can invite people. If you're a plain member, the button is hidden — ask an
owner or admin to send the invite for you.
</Callout>

</Step>

<Step>

### Enter their email and pick a role

Type the person's **email** address. Then choose a **role** — one of the cards below the email box.
Each role is explained in the next section; **Member** is the usual choice for a teammate who will
build and deploy.

</Step>

<Step>

### Send the invite

Choose **Email** to send through the instance's configured mail service, or **Copy link**
to share the invitation yourself. Both options invite the same email address with
the selected role. When email is unavailable, **Copy link** is selected for you.

Press **Send invite** or **Create invite link**. The panel shows the shareable link,
and the invitation stays under **Pending invitations** until it is accepted or revoked.

</Step>

</Steps>

<Callout title="Self-hosting Openship?" type="info">
In **Email** mode, the delivery menu shows which mail service will send the invite.
Use your configured mail service or, when connected, Openship Cloud. The panel links
to setup if the selected service is unavailable. Copyable links use the instance's
published address, including when you manage it from Desktop.
</Callout>

## What each role can do

A role is just a bundle of permissions. Openship has four, from most powerful to least:

- **Owner** — the person who created the workspace. Can do everything, including changing other
  people's roles and removing members. You can't invite someone straight in as owner — but an owner
  can promote an existing member to owner later, from the role dropdown on the Team tab.
- **Admin** — everything a member can do, **plus** manage members (send and cancel invites, remove
  people). On Openship Cloud, admins can also manage billing.
- **Member** — full read and write access to everything in the workspace: create projects, deploy,
  edit environment variables, and so on. A member **cannot** manage other people.
- **Restricted** — starts with **no** access. When you invite a restricted member you pick exactly
  which resources (specific projects, servers, and so on) they're allowed to reach. Use this for
  someone who should only touch one or two things.

<Callout title="Team roles are broad by design — invite people you trust (beta)" type="warn">
Owner, Admin, and Member are **coarse, high-trust roles**. A **Member** can deploy, create and
**delete** projects and servers, run jobs, manage domains, and read and write environment variables —
nearly everything an Admin can, minus managing people and reading the audit log. The roles differ only
in a narrow band (billing is owner-only; the audit log is owner/admin). So add someone as **Member or
Admin only if you'd trust them with near-admin control** of the workspace.

For a collaborator who should be limited to specific things, use the **Restricted** role with
per-resource grants, or hand out a **scoped / read-only [access token](/docs/security/permissions#access-tokens-follow-the-same-rules)**.
Those are the paths that actually enforce *read vs write vs admin* and confine access to specific
projects or servers — fine-grained, per-action limits for the standard roles are still on the roadmap
(**beta**), so treat a team organization as a **trusted-collaborator** workspace for now.

This is about permissions *inside* one workspace. **Between** organizations, isolation is enforced — one
org can never see or touch another's projects, servers, or secrets (see [Isolation](/docs/security/isolation)).
</Callout>

<Callout title="Changing a role later" type="info">
Only the **owner** can change someone's role. On the Team tab, each member (except you) has a role
dropdown next to their name — pick a new role and it applies right away. Owners and admins can also
**remove** a member with the trash icon; Openship asks you to confirm first. You can't change or
remove yourself.
</Callout>

<Callout title="Granting server access is high-blast-radius" type="warn">
Giving a member access to a **server** (when inviting, or by editing their access on the Team tab) is a
bigger deal than a role change: on that server they can reach every deployment and its **data**, the apps
running on it, injected **secrets/env vars**, a live **terminal**, and any **GitHub tokens** used for its
deploys. Because of that, Openship shows a **confirmation** that spells out exactly what the new access
exposes before it takes effect. Grant server access only to people you trust with everything on that box.
</Callout>

For the full rules on how permissions and per-resource access are enforced, see
[Permissions & roles](/docs/security/permissions).

## Accept an invite

This is what the *invited* person does after you send it.

<Steps>

<Step>

### Open the invitation link

Open the link from the email or the person who invited you. It opens a page that says
**You're invited** (or **Join [workspace name]** once you're signed in).

</Step>

<Step>

### Sign in or create an account

If you're not logged in yet, the page offers **Sign in** and **Create account**. Use the **same email
address the invite was sent to** — Openship checks that they match.

On self-hosted Openship, the instance administrator can create a brand-new user through this
invitation page. Workspace admins can invite users who already have an account, but they cannot mint
new instance accounts; ask the instance administrator to send the first invitation in that case.

</Step>

<Step>

### Press Accept

Once signed in with the right email, the page shows the workspace name and the role you're joining as,
with **Decline** and **Accept** buttons. Press **Accept**. You'll see **You're in**, and Openship
sends you to the dashboard for that workspace.

</Step>

</Steps>

## Personal vs team workspaces

Every Openship workspace is called an **organization**. When you first sign up, Openship creates a
**personal workspace** just for you — your own projects, servers, and domains, with no one else in it.

You have two ways to work with other people:

- **Invite them into your personal workspace.** Fine for a small group — everyone shares the same
  projects and servers. Use the **Invite member** button described above.
- **Create a separate team organization.** A clean, shared space that stays isolated from your
  personal projects. On the Team tab (while viewing your personal workspace) you'll see a **Create a
  team organization** card — press **Create team**, give it a name, and Openship switches you into the
  new shared workspace. Its projects and members are completely separate from your personal ones.

You can belong to more than one organization and switch between them. A team organization has its own
members and roles, exactly as described above.

<Callout title="Which should I pick?" type="info">
If it's just you and one or two trusted people, inviting into your personal workspace is simplest. If
you want a shared space that isn't tangled up with your own experiments — or you expect the group to
grow — create a team organization.
</Callout>

## Troubleshooting

<Callout title="“This invite is for … You're logged in as …”" type="warn">
The invite was sent to one email but you're signed in with a different one. Sign out, then sign back
in (or create an account) using the exact address the invitation was sent to. If you've lost the link,
ask an owner or admin to copy it from **Pending invitations** or send a fresh one.
</Callout>

<Callout title="The invite email never arrived" type="warn">
Check the spam folder first, then check the instance's selected mail service.
You can copy the existing link from **Pending invitations** and send it directly;
there is no need to create another invitation. For new invitations, choose **Copy link**
if email delivery is unavailable.
</Callout>

<Callout title="“Failed to send invite”" type="error">
Usually this means you don't have permission (only owners and admins can invite) or the person is
already a member. Confirm your own role on the Team tab, and check the **Active members** and
**Pending invitations** lists to see if they're already there.
</Callout>

## Related guides

<Cards>
  <Card title="Permissions & roles" href="/docs/security/permissions" description="The full picture of how Openship decides who can do what, including per-resource grants." />
  <Card title="Core concepts" href="/docs/getting-started/core-concepts" description="What an organization, project, server, and deployment actually are." />
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="Now that your team is set up, put an app online." />
</Cards>