Skip to main content
Every account works inside an organization, and every user has a default org of their own. 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 Machine 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

Create an org and manage its roster

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 is fixed. It 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 their owner’s default org or delete them first.
  • Org API keys outlive the person who made them. A --kind org key keeps working after its maker leaves, so CI doesn’t break when someone moves on. Every admin sees the org’s org keys, with who made each one, in boxd auth keys list and on the console’s API keys page, and can revoke them. When someone leaves, check the keys they made. See API keys.
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 is created from that snapshot unless they pick another one, which is how a team hands every new machine the same starting point. See Snapshot your app.
An org admin has team-admin authority on every team. A team admin has it on their own team.

Create a machine for a member

An owner or admin can create a machine that belongs to another member from the start, ready to work: their team’s snapshot, the packages and secrets they need, and their own integrations and agent logins. It takes a machine spec with assignTo, from the SDKs or the API:
The machine is private to the member and billed to the org, and the admin who created it can’t reach it afterwards. It runs the spec the admin wrote, packages as root included, with the member’s own credentials, so assign only a spec the member would run themselves. See Create a machine for someone else. The secrets such a machine gets are usually the org’s unattached secrets, which reach only the machines whose spec lists them. Only owners and admins can set, move or remove an org’s unattached secrets, or list one in a spec. A member’s own unattached secrets are theirs. See Unattached secrets.

Regions

Every org runs machines in both Frankfurt and New York. Members, roles, teams, secrets and billing are the same in both. Owners and admins set the org’s default region, where new machines go when nobody picks one.
A team’s default snapshot is per region, since a snapshot lives in one region. boxd teams set-default-snapshot backend base.nyc sets the one new team machines in New York start from. See Regions.

From the SDKs

See Organizations and Teams in the TypeScript reference, and the same sections in the Python 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.