# Orgs and teams

An **org** is a shared account: its machines, VPCs, addresses, rules, API keys and bill belong to
the org, and you invite people into it. Everyone starts with a personal org of their own; you can
make more and belong to as many as you're invited to.

**Teams** split an org into groups of people. A machine, VPC or address is either **org-wide**
(everyone in the org sees it) or **in a team** (only that team, and the org's owners and admins,
see it). Teams are about who can see and use what; they aren't a firewall (see Networking below).

## Roles

Everyone in an org has one role:

| | Owner | Admin | Member | Viewer |
|---|---|---|---|---|
| See machines | all | all | their teams' and org-wide | their teams' and org-wide |
| Shell, commands, files, wake, sleep | all | all | what they see | no (read only) |
| Create machines | yes | yes | yes, into one of their teams | no |
| Delete and resize machines | all | all | what they see | no |
| Notes | read and write | read and write | read and write, on what they see | read |
| Rules for agents | set, delete | set, delete | set | read |
| Invite and remove people, change roles | yes | yes (not owners) | no | no |
| Teams, and where things go | yes | yes | no | no |
| API keys and connected agents | all of the org's | all of the org's | their own | none |

- **An API key acts as the person who made it,** with their role and teams, in the org it was made
  in. Remove someone and their keys in that org stop working.
- **An org always has an owner:** the last owner can't leave or be demoted.
- **A member on no team** sees only org-wide things and can't create until an admin puts them on
  one.

## Switching orgs

Your SSH key acts in one org at a time; your personal org until you switch. The status line in the
app shows which.

- **In the app:** Account → Org → Overview, pick an org, `enter`. The app restarts in it.
- **Over ssh:** `ssh org@shell.639cloud.com switch "Org name"`. The next session uses it.

A connection that's already open stays in the org it started in: an agent connected over MCP, or
an API key, never wanders into another org because you switched.

## Inviting people

Owners and admins invite by email, with a role and optionally teams:

```
ssh org@shell.639cloud.com invite ann@example.com --role member --team web
```

or in the app: Org → Members → `i`. The invite waits for them for 14 days. If they don't have an
account yet, the invite also lets them sign up with that email. It shows up in their Inbox: they
accept with `y` (or decline with `d`), or with `ssh org@shell.639cloud.com accept ID`, and you're
told either way.

Removing someone (`remove EMAIL --yes`, or Members → `d`) takes effect at once: their API keys
there are revoked, their connected agents are cut off, and their open shells, file transfers and
commands end within seconds. The same happens to a shell on a machine moved to a team they're not
on.

An org can have 25 invites waiting at once, and one person can send 50 a day.

## Teams and where things go

```
ssh org@shell.639cloud.com team new web
ssh org@shell.639cloud.com team add web ann@example.com
ssh org@shell.639cloud.com assign my-machine web       # a machine
ssh org@shell.639cloud.com assign vpc:backend web      # a VPC
ssh org@shell.639cloud.com assign ip:ADDRESS org       # back to org-wide
```

In the app: Org → Teams makes (`n`) and deletes (`d`) teams, Members → `t` puts a person on
teams; a machine's page has a Team line
(owners and admins change it); the VPC and IP lists have a TEAM column and `t` moves the selected
one to the next team.

- **What a member creates goes into their team.** On several teams, they pick one (`t` on the
  create screen; agents and the API pass the team).
- **A fork stays in its source's team.**
- **A team can't be deleted while it has machines, VPCs or addresses:** move them first.
- **Things that existed before teams** start org-wide.

## Networking

The org is the hard boundary: different orgs never share a VPC, an address or a link. Inside an
org:

| | Who creates | Who uses |
|---|---|---|
| VPCs | owners, admins, and members (into their team) | anyone who can see both the machine and the VPC |
| Public IPv4s | owners and admins reserve and release them (they're billed) | anyone who can see both the machine and the address |
| Wake links, inbound ports, internet rules | part of the machine | whoever can use the machine |

- **Teams aren't a firewall:** machines in different teams reach each other privately only if they
  share a VPC, just as before.
- **An org-wide VPC** is the usual way for teams to share a private network.
- **Moving a machine to another team** keeps its VPC and address.
- **Members delete only their team's VPCs;** org-wide ones are for owners and admins.

## For agents

An agent sees exactly what the person whose key it uses sees. The MCP `whoami` tool reports the
org, role and teams, and `list_machines` shows each machine's team. `GET /v1/org` does the same
over the API.