Limits and defaults
Every Cubicle limit and default in one place, covering Box vCPU, memory and disk ranges and base image sizes, name rules, exec timeouts and output limits, request body size, rate limits, auto-hibernation, SDK and CLI wait timeouts, API key expiry, session lifetimes, private network sessions and what is not available yet.
These are the values on api.cubicle.sh. They may change. Values marked "SDK default" are options
you set in the SDK, for a client or per call.
Box resources
| Resource | Minimum | Maximum | default image | omarchy image |
|---|---|---|---|---|
vCPUs (vcpus) | 1 | 64 | 2 | 4 |
Memory (memoryMiB) | 256 MiB | 262,144 MiB (256 GiB) | 2048 MiB | 8192 MiB |
Disk (diskGiB) | 1 GiB | 2048 GiB | 12 GiB | 40 GiB |
All three are whole numbers. The image columns are the sizes a Box created from that base image gets when you leave them out. Resources explains defaults, placement and reservations, and Size rules covers Boxes created from a snapshot.
Names
| Name | Rule | Pattern | Unique among |
|---|---|---|---|
| Box | 1 to 63 lowercase letters, digits and dashes, starting with a letter or digit | ^[a-z0-9][a-z0-9-]{0,62}$ | The organization's Boxes that are not deleted |
| Generated Box name | box- and 6 hex characters, such as box-1a2b3c, when you leave the name out | ^box-[0-9a-f]{6}$ | As above |
| Organization | Same rule as a Box name | ^[a-z0-9][a-z0-9-]{0,62}$ | All organizations |
| Service account | Same rule as a Box name; its identity is ORG/NAME | ^[a-z0-9][a-z0-9-]{0,62}$ | The organization's service accounts that are not deleted |
| API key | 1 to 63 lowercase letters, digits, ., _ and -, starting with a letter or digit | ^[a-z0-9][a-z0-9._-]{0,62}$ | The service account's keys that are not revoked |
| Snapshot | Same rule as an API key name | ^[a-z0-9][a-z0-9._-]{0,62}$ | Not unique; use the snapshot's ID |
A deleted Box's name is free for a new Box as soon as the delete is accepted. See Boxes.
Exec
| Setting | Default | Limit |
|---|---|---|
argv | Required | 1 to 1024 strings of up to 65,536 characters each; the 64 KiB request body limit applies first |
timeoutMs | 60,000 ms (60 s) | At least 100 ms. Larger values than 600,000 ms (10 min) are lowered to it without an error |
maxOutputBytes | 65,536 bytes (64 KiB) | At least 0. Larger values than 1,048,576 bytes (1 MiB) are lowered to it without an error |
cwd | The account's home directory | An absolute path of up to 4096 characters |
maxOutputBytesis one budget for stdout and stderr together. Output past it is discarded andtruncatedistrue.- A command that runs out of time ends with
timedOut: trueand exit code124. - List a Box's operations returns the 50 most recent operations.
See Run commands.
API
| Item | Value |
|---|---|
| Request body | At most 64 KiB; larger bodies fail with 413 payload_too_large |
Idempotency-Key | 1 to 200 characters, kept for 7 days |
| Requests per user or service account | 600 a minute |
Non-GET requests per user or service account | 120 a minute |
| Refused requests before an address is blocked | 30 an hour |
| Automatic address block | 60 minutes |
| Sign-in requests, including device sign-in starts | 20 a minute per client address, 300 a minute in all |
| Device sign-in polls | 120 a minute per client address, 3000 a minute in all |
| Pagination | None: lists return every item, except a Box's operations (the 50 most recent) |
See Rate limits and Requests and waiting.
Lifecycle and waiting
| Item | Value |
|---|---|
| Automatic hibernation | 60 minutes after the Box first reports running following a start, whatever its activity |
| Stop | The guest is asked to shut down, and turned off if it has not stopped within about 15 s |
| Boot timeout | 180 s; then the start fails with guest did not become reachable |
| Retry after a failed hibernation | 30 s, then twice as long each time, up to 5 minutes |
| SDK lifecycle waits | SDK default 5 minutes: create, start, stop, hibernate, delete and waitUntil |
SDK exec wait | The command's timeoutMs plus 2 minutes |
SDK snapshot, restore and operations.wait | SDK default 15 minutes |
| SDK polling | SDK default every 1 s, at most 5 polls a second per client |
| SDK and CLI request timeout | 30 s per HTTP request: SDK default (requestTimeoutMs), fixed in the CLI |
CLI --wait | 10 minutes, polling every 1 s |
CLI exec, snapshot and restore | Poll every 500 ms with no deadline |
See Box lifecycle and Waiting.
Keys and sessions
| Item | Value |
|---|---|
| API key expiry | 1 to 3650 days, or never when no expiry is given |
| API key scopes | read (GET only) or write |
| API key token | Shown once, when the key is created |
| Sign-in session | 30 days from sign-in; using it does not extend it |
| Device sign-in code | Expires after 600 s; poll every 2 s |
| SSH keys | ssh-ed25519 only, up to 1000 characters; the comment is cut to 200 characters |
See Sign in and API keys and Authentication.
Private network and console
| Item | Value |
|---|---|
| Private network session | 30 s, renewed by the CLI every 10 s, and never past the expiry of the sign-in session that opened it |
| Credentials | A sign-in session; API keys cannot open private network sessions |
| Open console viewers | 8 per person |
See Networking and Use the desktop console.
Not available yet
- Streaming exec output, and exec with stdin or a TTY. Output arrives when the command ends.
- File upload and download APIs. See Move files into and out of a Box.
- Port forwarding, proxies and public URLs. Boxes are reachable only over the private network.
- Forking, resizing, renaming and rebooting a Box. A reboot inside the guest leaves the Box
failed; start it again. - Deleting a single snapshot. Snapshots are deleted with their Box.
- Network connections to a Box from the SDK, and SSH or private network access with API keys. To
reach a service in a Box from code, run the client inside the Box with
exec. - A
hibernatecommand in the CLI. Use the SDK, the API or the Dashboard. - The CLI on Windows.
Networking
How Cubicle networking works, covering each Box's private IPv4 address, the WireGuard path from the cubicle CLI through Gateway, private DNS names under cubicle.internal, expiring access sessions, grants, SSH host-key pinning, outbound internet access and when to use SSH, the private network or the exec API.
Troubleshooting
Fixes for Cubicle errors listed by the exact message you see, covering CLI sign-in and API key errors, permission and rate-limit refusals, capacity, Box states such as failed and restartRequired, SSH readiness and CLI installation, with an index of the SSH, private network, console, command, snapshot, hibernation and member errors that their guides fix.