Organizations and teams

Every account works inside an organization, and your personal account counts as one. An org is where machines are billed, where sharing happens, and where secrets live. This page is about the org itself: its members, their roles, and the teams inside it. For what sharing does to a machine, see VM sharing. Everything here is available from the console’s Organization page, from boxd auth org and boxd teams on the CLI, and from the SDKs’ orgs and teams namespaces.

Roles

Role	Can
member	use the org’s shared machines, create org-billed machines, read the org’s settings
admin	everything a member can, plus invite and remove members, change roles, rename the org, set org-wide defaults, create teams
owner	everything an admin can, plus demote other admins. There is one owner, and ownership is transferred by the boxd team on request

Create an org and manage its roster

boxd auth org new "Acme"                        # you become owner and admin; the CLI switches to it
boxd auth org rename "Acme Labs"                # admin only
boxd auth org members                           # roster, plus pending invites for admins (alias: ls)
boxd auth org invite dev@example.com --role member   # admin only; emails the link and prints it too
boxd auth org revoke-invite <token>             # admin only
boxd auth org remove-member <user_id> -y        # admin only; plain members only
boxd auth org set-role <user_id> admin          # promote; `member` demotes

A few rules keep the org safe from its own credentials:

Invites carry a role. The invitee lands as member or admin, and an admin invite can only be sent from an interactive login. An API key or a token minted inside a machine cannot send one, and cannot read the links of pending invites either. It still sees that an invite is pending.
Demoting another admin is owner-only. An admin can always demote themselves.
The owner’s role cannot be changed with set-role, and an owner or admin cannot be removed with remove-member. Both go through the boxd team.
A member who still owns org-billed machines cannot be removed. Move those machines to personal billing or destroy them first.

Every one of these commands follows the active org context, so boxd auth switch acme first, or pass --org acme for one call.

Teams

A team is a group of members inside an org, with an optional default snapshot. A machine created by a team member boots from that snapshot unless they pick another one, which is how a team hands every new machine the same starting point. See Golden image.

boxd teams new backend                          # org admin only
boxd teams list                                 # every team for an admin; your own teams otherwise (alias: ls)
boxd teams get backend                          # roster and default snapshot
boxd teams add-member backend <user_id>         # team admin only; must already be an org member
boxd teams remove-member backend <user_id>
boxd teams set-role backend <user_id> admin
boxd teams set-default-snapshot backend golden  # must be a shared snapshot
boxd teams set-default-snapshot backend --clear
boxd teams rename backend platform
boxd teams destroy backend -y                   # alias: rm

An org admin has team-admin authority on every team. A team admin has it on their own team.

From the SDKs

org = boxd.orgs.create("Acme")
boxd.orgs.get_members("acme")                       # OrgMembers(members, invites)
boxd.orgs.invite("dev@example.com", role="member", org="acme")
boxd.orgs.set_member_role("usr_...", "admin", org="acme")
boxd.orgs.remove_member("usr_...", org="acme")

team = boxd.teams.create("backend", org="acme")
boxd.teams.add_member(team.id, "usr_...")
boxd.teams.set_default_snapshot(team.id, snapshot.id)

const org = await boxd.orgs.create("Acme");
await boxd.orgs.getMembers("acme");                 // { members, invites }
await boxd.orgs.invite("dev@example.com", { role: "member", org: "acme" });
await boxd.orgs.setMemberRole("usr_...", "admin", "acme");
await boxd.orgs.removeMember("usr_...", "acme");

const team = await boxd.teams.create("backend", "acme");
await boxd.teams.addMember(team.id, "usr_...");
await boxd.teams.setDefaultSnapshot(team.id, snapshot.id);

See Organizations and Teams in the Python reference, and the same sections in the TypeScript reference.

Live everywhere

A change made on one surface shows up on the others without a reload. Invite someone from the CLI and the console’s Organization page lists the invite as it lands. The same goes for role changes, team rosters, and every machine setting.

Getting started

Guides

Integrations & automations

Use cases

References

Organizations and teams

Roles

Create an org and manage its roster

Teams

From the SDKs

Live everywhere

​Roles

​Create an org and manage its roster

​Teams

​From the SDKs

​Live everywhere

Roles

Create an org and manage its roster

Teams

From the SDKs

Live everywhere