> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> Pool VMs across a team under one bill, with shared machines any member can reach.

An **organization** lets a team work out of one boxd account: machines are billed to the org instead of to individuals, and any machine can be **shared** so every member can SSH straight into it. One golden VM, one preview fleet, one set of long-running services — reachable by the whole team, paid for once.

Each member keeps their own login. Sharing a machine is always an explicit, owner-controlled step, and boxd guarantees a **clean handoff**: a member's personal agent credentials are never left readable on a machine the rest of the team can reach. See [Share a VM](/organizations/share-a-vm) for exactly how that works.

<Note color="#E05A6D">
  Organizations are set up by the boxd team. If you're running boxd with a team and want shared billing and machines, [reach out](mailto:contact@boxd.sh) — we'll create your org and make you its owner. From there you (and any admins we appoint) add and remove members yourself.
</Note>

## The three machine states

Inside an organization, every VM is in exactly one of three states:

| State                   | Who can see & reach it      | Who pays |
| ----------------------- | --------------------------- | -------- |
| **Personal**            | You only                    | You      |
| **Org-billed, private** | You only                    | The org  |
| **Shared**              | **Every member** of the org | The org  |

* **Personal** is the default and behaves exactly as it does outside an org — your machine, your bill.
* **Org-billed, private** is what `boxd machine new` creates while you're working in an org context: the org picks up the bill, but the machine stays private to you until you choose to share it.
* **Shared** opens the machine to the whole team — every member can `connect` and SSH in, and the org pays.

Promoting a machine from private to shared, and back, is a one-command toggle covered in [Share a VM](/organizations/share-a-vm).

## Roles

An organization has three roles. **Roles are assigned by the boxd team** — there's no self-serve promotion today.

| Role       | What they can do                                                                                                                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**  | One per org — the accountable, billing party. Everything an admin can do, plus they're the org's permanent point of contact (only the boxd team can transfer ownership).                                  |
| **Admin**  | Zero or more. Same self-serve powers as the owner: **invite and remove members** from the [console](#managing-members), and manage the org's machines. Admins are appointed and removed by the boxd team. |
| **Member** | Create org-billed machines within quota, reach every **shared** machine in the org, and share or unshare **their own** machines.                                                                          |

In the self-serve console the **owner and admins are equivalent** — both manage members. Appointing admins, transferring ownership, and deleting an org are operator actions; [reach out](mailto:contact@boxd.sh) to change them.

<Note color="#E05A6D">
  Don't confuse the org **Owner** role with **per-machine ownership**. Whoever creates a machine owns *that machine* and decides whether it's private or shared — including the org owner's machines and every member's. Being an org owner or admin doesn't grant a shell on another member's *private* machine; only *shared* machines are reachable org-wide.
</Note>

## Working in an org context

Your **context** decides which org a new machine is billed to and which machines `list` and `connect` see. By default you land in your org; switch back to personal any time.

```bash theme={"theme":"github-dark"}
boxd auth                        # organizations you belong to (active one marked)
boxd auth switch acme            # work in the "acme" org context
boxd auth switch personal        # back to your personal context
```

While you're in an org context:

* `boxd machine new` creates an **org-billed, private** machine. Add `--shared` to make it visible to the whole org from the moment it boots.
* `boxd machine list` shows the org's machines, shared ones first, and tags your private org-billed machines so you can tell them apart.
* `boxd manage billing` reflects the **org's** plan and quota, not your personal one.

```bash theme={"theme":"github-dark"}
boxd machine new staging                  # org-billed, private to you
boxd machine new staging --shared         # org-billed and shared with the whole org
```

## Managing members

Day-to-day org work — switching context, listing machines, sharing and unsharing — is fully scriptable from the **boxd CLI** (shown above). **Membership** is the one piece that lives in the **console**: the owner and any admins invite and remove members there directly, no operator ticket required.

<Steps>
  <Step title="Open the Organizations page">
    Go to [boxd.sh/app](https://boxd.sh/app), open the profile menu (top right), and choose **Organizations** — the direct route is [`/app/organizations`](https://boxd.sh/app/organizations). If you belong to more than one org, pick the right one in the org switcher at the top of the page. (The Organizations entry only appears while you're in an org context.)
  </Step>

  <Step title="Invite a member">
    Under **Invite a member**, enter your teammate's email and click **Create invite**. boxd emails them the invite link and copies a shareable link to your clipboard so you can send it directly. Each link is **single-use** and expires after **48 hours**.
  </Step>

  <Step title="They join with GitHub">
    Your teammate opens the link and signs in with GitHub. That's it — they're a member, the org's machines show up for them, and they can reach every shared VM. Pending invites are listed on the same page, where you can **Copy link** or **Revoke** them.
  </Step>
</Steps>

To remove someone, click **Remove** next to their name on the same page. They lose access to all org VMs immediately. Creating the org itself, and changing its plan or quota, is handled by the boxd team — [reach out](mailto:contact@boxd.sh).

## Who can reach what

| Action           | Personal machine | Org-billed, private | Shared         |
| ---------------- | ---------------- | ------------------- | -------------- |
| Connect / SSH in | VM owner         | VM owner            | **Any member** |
| Share / unshare  | —                | **VM owner**        | **VM owner**   |
| Counts against   | Your quota       | Org quota           | Org quota      |

## Next steps

<Columns cols={2}>
  <Card title="Share a VM" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/share.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=3728787098861b8f28c5076d71f02278" href="/organizations/share-a-vm" width="16" height="16" data-path="images/icons/share.svg">
    Open a machine to your team, and the credential handoff that keeps it clean.
  </Card>

  <Card title="CLI reference" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/command.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=6c33d9e29e4e937c0950311233ec5659" href="/reference/external-cli#organizations" width="16" height="16" data-path="images/icons/command.svg">
    Every org command and flag in one place.
  </Card>
</Columns>