Organizations and access
How Cubicle access control works, covering organizations and personal organizations, Box creation approval, the owner, admin and member roles, Box grants, guest accounts in a Box, revoking access and what service accounts can do.
Every Box belongs to one organization. People and service accounts are members of organizations with a role, and a role decides what they can manage. Shell-level access to a Box (running commands, SSH, the private network and the console) also needs a grant on that Box.
People act with a sign-in session, and service accounts with API keys. Sign in and API keys covers both: how to get them, their lifetimes, key scopes and the routes API keys can call.
Organizations
- An organization holds Boxes, their snapshots and operations, members and service accounts.
- Organization names match
^[a-z0-9][a-z0-9-]{0,62}$and are unique across Cubicle. API paths accept an organization's name or its ID. - Cubicle creates organizations and adds their first members; you cannot create one yourself. Every account also gets a personal organization (see below).
- To add a colleague to an organization, see Add a person.
GET /v1/melists your organizations, each with yourrole, whether it is yourpersonalorganization and whether it can create Boxes (boxCreateAllowed).
Personal organizations
- Cubicle creates a personal organization the first time you sign in, with you as its owner.
- Its name is based on your email address, for example
jane-doeforjane.doe@example.com. - A personal organization starts with Box creation turned off. Until Cubicle turns it on,
creating a Box there fails with
403 box_create_disabled, and the Dashboard does not offer it when you create a Box.
Box creation approval
Each organization has a boxCreateAllowed setting that only Cubicle can change. It is on for
organizations that Cubicle creates for you and off for personal organizations. When it is off,
POST /v1/orgs/{org}/boxes returns 403 box_create_disabled, including for Boxes created from a
snapshot. Existing Boxes keep working.
Roles
Each member has one role in each organization: owner, admin or member.
| Action | member | admin | owner |
|---|---|---|---|
| See the organization's Boxes and members, and each Box's snapshots and operations | Yes | Yes | Yes |
| Create a Box, when the organization allows it | Yes | Yes | Yes |
| Start, stop, hibernate or delete a Box | With a grant | Any Box | Any Box |
| Take a snapshot of a Box or restore it | With a grant | Any Box | Any Box |
| Create a Box from a snapshot | With a grant on the source Box | Any snapshot | Any snapshot |
| Run commands (exec), SSH, use the private network or the console | With a grant | With a grant | With a grant |
| Read a command's output | Own commands only | Own commands only | Own commands only |
| Grant a member access to a Box | No | Yes | Yes |
| Revoke a grant | Own grant only | Any grant | Any grant |
| Add an existing user to the organization | No | As member or admin | Any role |
| Remove a member | No | Yes | Yes |
| Create and delete service accounts, issue and revoke API keys | No | Yes | Yes |
- Whoever creates a Box gets a grant on it automatically.
- The last owner of an organization cannot be removed:
409 last_owner. - Only members of a Box's organization can see the Box. For anyone else, requests for it return
404, as if it did not exist. - Exec output belongs to the person or service account that ran the command. Other members
can see that the operation exists, but its
resultisnullfor them. See Commands and operations.
Box grants
A grant gives one member access to one Box. Owners and admins grant access to any active member of the Box's organization, including themselves. Grants are managed with a sign-in session, not with API keys. Grant access to a Box has the steps.
| With a grant on a Box, you can | Also needed |
|---|---|
| Run commands with the exec API | The Box must be running |
| SSH into it | An ssh-ed25519 key on your account, and the CLI |
| Reach it over the private network | The CLI and its tunnel helper; no SSH key |
| Open its desktop console in the Dashboard | The Box's console must be ready |
| Start, stop, hibernate, delete, snapshot and restore it | Nothing more; owners and admins can do this without a grant |
| Create Boxes from its snapshots | The organization must allow Box creation |
Admins need a grant too
The owner and admin roles never give shell-level access by themselves. Exec and the console fail
with 403 forbidden "an explicit box grant is required", and the private network does not route
the Box, until an owner or admin grants it. Admins can grant a Box to themselves.
Guest accounts
- A grant creates your guest account in the Box:
jv_followed by the first 12 hex digits of your user ID.jv_is a legacy prefix. The name is the same on every Box. - The account's home directory is
/home/jv_…and its shell is/bin/bash. It belongs to a group with passwordlesssudo. - Exec commands and SSH logins run as this account. Your account's SSH keys are installed for it.
- While your account has no SSH key, your guest account is locked and expired in the Box, as every
service account's is; Root and sudo explains what that
means for
sudo. - The Node applies grant and SSH key changes inside the Box, including while it runs.
GET /v1/boxes/{box}/grantslists each grant'sstatus,guestAccount,desiredRevisionandappliedRevision; a change has been applied when the two revisions match.
Revoking access
- An owner or admin can revoke any grant. A member can revoke only their own.
- Revoking a grant locks the guest account, removes its SSH keys and ends private network access to the Box, including open connections.
- Files in the account's home directory stay on the Box's disk.
- Removing a member from the organization ends their access to all of its Boxes.
Service accounts
A service account is a non-interactive member for automation: CI jobs, scripts and AI agents.
One organization owns it, and its identity is ORG/NAME, for example acme/ci.
- Its role is
member(the default) oradmin, neverowner. It cannot join other organizations and never signs in. - It authenticates only with API keys. Creating and deleting service accounts, their keys and what removing one ends are covered in Service accounts and API keys.
- It gets Box grants like a person. A Box it creates is granted to it automatically. Grant other Boxes to it with its ID.
- Its commands run as its own guest account in the Box.
- With the
adminrole it can start, stop, hibernate, delete, snapshot and restore any Box in its organization, and create Boxes from any snapshot in its organization. Exec still needs a grant. - It cannot use SSH, the private network or the console, and it cannot manage members, grants, service accounts or API keys. Those need a sign-in session.
Related
Sign in and API keys
Credentials, scopes, key lifecycle and the routes API keys can call.
Manage organization members
Add and remove people, change roles and grant access to Boxes.
Run CI jobs in Boxes
Run Boxes from CI and scripts with an API key.
Account and access commands
cubicle members, grants, service-accounts, api-keys and sessions.
Networking
Private network access, SSH and expiring access sessions.
Boxes
What a Box is, a QEMU/KVM virtual machine with its own Linux kernel and disk, with its isolation boundary, Boxes vs containers, the default and omarchy base images, vCPUs, memory and disk and how they are placed and reserved, free Omarchy Boxes and their automatic deletion, names, IDs, Box references and the Box object's key fields.
Box lifecycle
Box states (pending, provisioning, starting, running, stopping, stopped, hibernating, hibernated, deleting, failed, unknown), the requests that move a Box between them, auto-hibernation 60 minutes after each start, what stop, hibernate and delete keep, restartRequired after host restarts, failures, deletion, desired vs observed state and generations, and ssh.ready with what each ssh.reason means and what to do.