Concepts
How Cubicle works, with a link to each concept page (Boxes, organizations and access, Box lifecycle, commands and operations, snapshots, networking) and a glossary of Box, Node, organization, personal organization, member, role, grant, guest account, service account, API key, session, exec, operation, generations, connection generation, Gateway, tunnel, device, access session, snapshot, hibernation, base image, template Box and free Omarchy Box.
These pages explain how Cubicle works, so that the steps in the guides make sense. Each page covers one topic, and the glossary below defines the words they use.
- Boxes: what a Box is, its images, resources, names and references.
- Organizations and access: roles, grants, guest accounts and service accounts.
- Box lifecycle: states, hibernation, deletion, generations and readiness.
- Commands and operations: how exec runs a command, and the operations that record requests.
- Snapshots: disk copies of a stopped Box, restores and new Boxes from them.
- Networking: private addresses, Gateway, private DNS, access sessions and outbound traffic.
Glossary
Each term links to the page that explains it.
| Term | Meaning |
|---|---|
| Access session | A short-lived lease that lets one of your devices reach your Boxes over the private network. |
| API key | A secret token, starting with cbk_, that authenticates as one service account in its organization. Its scope is read or write. |
| Base image | The disk image a new Box starts from when it is not created from a snapshot: default or omarchy. |
| Box | A Linux virtual machine that Cubicle runs for you, with its own kernel, disk and private IPv4 address. It belongs to one organization and lives on one Node. |
| Connection generation | A Box's connectionGeneration, the counter that SSH and private-network access are tied to. Access from an earlier value no longer applies. |
| Device | A computer registered for the private network, with its own WireGuard key and tunnel address. |
| Exec | Running one command in a Box through the API, the SDK or the CLI, without SSH. Each exec is an operation. |
| Free Omarchy Box | A Box from the free Omarchy sign-up in the Dashboard, marked pooled: true. It is the only kind of Box that Cubicle deletes on its own. |
| Gateway | Cubicle's relay for the private network. It terminates your WireGuard tunnel and answers private DNS for cubicle.internal. |
| Generation | A counter that shows whether a request has taken effect: desired.generation is the latest request, and observed.generation the last one the Box's Node applied. |
| Grant | Permission for one member to use one Box: run commands, SSH, the private network and the desktop console. |
| Guest account | The Linux account in a Box for one person or service account with a grant. Exec commands and SSH logins run as it. |
| Hibernation | Saving a running Box's memory and processes on its disk and stopping the VM; a start resumes it where it was. |
| Member | A person or service account that belongs to an organization, with one role in it. member is also the name of the role with the fewest permissions. |
| Node | A Cubicle host machine that runs Boxes. A Box stays on one Node for its whole life. |
| Operation | The durable record of an exec, snapshot or restore request. It starts pending and ends done, failed or unknown. |
| Organization | The account that owns Boxes, their snapshots and operations, members and service accounts. |
| Personal organization | The organization Cubicle creates for you at your first sign-in, with you as its owner. |
| Role | What a member may manage in an organization: owner, admin or member. Shell access to a Box needs a grant as well. |
| Service account | A non-interactive member of one organization, for CI jobs, scripts and AI agents. It authenticates with API keys. |
| Session | The sign-in session a person gets from the Dashboard or cubicle login. Unlike an API key, it can manage access and use SSH, the private network and the desktop console. |
| Snapshot | A named copy of a stopped Box's disk. You can restore the Box to it or create new Boxes from it. |
| Template Box | A Box you set up once and snapshot, so that new Boxes start from that snapshot. |
| Tunnel | The WireGuard connection from your computer to Gateway, run by a root helper that cubicle tunnel install adds. You need it only for the private network and SSH. |
Manage organization members
List, add and remove members of a Cubicle organization, change their owner, admin or member role, and grant or revoke their access to Boxes, including service accounts, with the cubicle CLI or the HTTP API and a sign-in session.
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.