SDK reference

Type Aliases

ApiKeyScope

type ApiKeyScope = "read" | "write";

read keys may only make GET requests; write keys may use every route that takes keys.

BoxInfo

type BoxInfo = object;

A Box as the Cubicle API reported it when it was fetched. It does not update itself: call Boxes.get or BoxRef.info again for current values.

Properties

Property	Type	Description
`baseImage`	`string`	The base image ID, such as `default` or `omarchy`. A snapshot's Box keeps its source's.
`connectionGeneration`	`number`	Advances with every start, stop, hibernation (automatic ones too), deletion and restore, and when the Box's host restarts, but not when a failed hibernation returns the Box to running. Host keys, guest accounts and private-network access from an earlier value no longer apply, so SSH and private-network traffic reaches the Box only once it runs at the new value.
`console`	`Readiness`	Whether the desktop console can be opened now.
`createdAt`	`string`	When the Box was created, as an ISO 8601 timestamp.
`deletion`	`"pending"` \| `"complete"` \| `null`	`pending` from an accepted delete until its Node has removed the Box, after which listings no longer show it; otherwise `null`. `complete` appears only when a create repeated with the same `idempotencyKey` returns a Box that has been removed since.
`desired`	`object`	What the Box was last asked to be. `generation` advances with every accepted change.
`desired.generation`	`number`	-
`desired.state`	`DesiredState`	-
`expiresAt`	`string` \| `null`	When a stopped or hibernated free Box is deleted unless it is started again.
`hibernateAt`	`string` \| `null`	When a running Box hibernates automatically, 60 minutes after its current start first reported running. Activity does not extend it. `null` when none is scheduled.
`hibernationRetryAt`	`string` \| `null`	When Cubicle retries a hibernation that failed, or `null`.
`id`	`string`	The Box's ID, a UUID. It never changes and is never reused.
`name`	`string`	Unique among the organization's Boxes that are not deleted. Freed when the Box is deleted.
`node`	`object`	The Node (host) the Box lives on for its whole life. `healthy`: it reported recently.
`node.healthy`	`boolean`	-
`node.id`	`string`	-
`node.name`	`string`	-
`observed`	\| { `ageSeconds`: `number` \| `null`; `error`: `string` \| `null`; `fresh`: `boolean`; `generation`: `number` \| `null`; `observedAt?`: `string`; `state`: `string`; } \| `null`	The Node's last report about the Box, or `null` before its first report: the `state` it observed, the desired `generation` it had applied, its last `error` for the Box, when it reported (`observedAt`, `ageSeconds`), and whether the report is `fresh`.
`org`	`object`	The organization that owns the Box.
`org.id`	`string`	-
`org.name`	`string`	-
`pooled`	`boolean`	A free Box: its CPU and memory are reserved only while it runs.
`privateIp`	`string` \| `null`	Guest address on its Node's Box subnet, reached through Gateway.
`restartRequired`	`boolean`	The Box's host restarted while the Box was running. It stays down until started again.
`spec`	`Resources`	The Box's size.
`ssh`	`Readiness`	Whether exec and new SSH connections can be used now: the Box runs at its current generation. It does not check the caller's own access or SSH key.
`state`	`BoxState`	The Box's state, from its Node's last report. It may predate your latest request. `unknown` means the Node has not reported recently: neither running nor stopped.

BoxState

type BoxState = 
  | "pending"
  | "unknown"
  | "deleted"
  | "absent"
  | "provisioning"
  | "starting"
  | "running"
  | "stopping"
  | "stopped"
  | "hibernating"
  | "hibernated"
  | "deleting"
  | "failed";

A Box's state, as BoxInfo.state reports it: the state its Node last observed, or one Cubicle derives. pending means a new Box has no report yet. unknown means its Node has not reported recently, so the Box is neither known to be running nor stopped. Current Nodes never report absent.

CreateBoxOptions

type CreateBoxOptions = LifecycleOptions & object;

Options for Boxes.create.

Type Declaration

Name	Type	Description
`idempotencyKey?`	`string`	Makes the create safe to repeat: a second create with the same key and parameters returns the same Box. A new key is generated per call when omitted. Keys are 1 to 200 characters and are kept for 7 days. Reusing one with different parameters rejects with `idempotency_conflict`.

CreateBoxParams

type CreateBoxParams = object;

What Boxes.create creates. Every field is optional.

Properties

Property	Type	Description
`baseImage?`	`string`	A base image ID: `default` (the default) or `omarchy`; see Cubicle.listBases. Exclusive with `snapshotId`.
`diskGiB?`	`number`	Disk in GiB, 1 to 2048. Defaults like `vcpus`. With `snapshotId`, it may grow the source Box's disk but not shrink it.
`memoryMiB?`	`number`	Memory in MiB, 256 to 262144. Defaults like `vcpus`.
`name?`	`string`	Unique in its organization: 1 to 63 lowercase letters, digits and dashes, starting with a letter or digit. Generated (`box-` and six hex digits) when omitted.
`org?`	`string`	Organization name or ID. Defaults to the client's `org`, then the API key's organization.
`snapshotId?`	`string`	Create from a completed snapshot, by its ID; see Cubicle.listSnapshots. The Box is placed on the snapshot's Node and keeps its source's base image.
`start?`	`boolean`	`false` creates the Box stopped; `create` then returns without waiting. Default `true`.
`vcpus?`	`number`	Virtual CPUs, 1 to 64. Defaults to the base image's size, or the source Box's for `snapshotId`.

CreationBase

type CreationBase = object;

A base image and whether any Node can place it: available is true when a healthy Node has the image. It does not consider free capacity.

Properties

Property	Type
`available`	`boolean`
`id`	`string`
`name`	`string`
`spec`	`Resources`

CreationSnapshot

type CreationSnapshot = object;

A completed snapshot the caller may create a Box from.

Properties

Property	Type	Description
`box`	`object`	The Box it was taken from.
`box.id`	`string`	-
`box.name`	`string`	-
`createdAt`	`string`	When it was requested, as an ISO 8601 timestamp.
`id`	`string`	The snapshot's ID, for `create`'s `snapshotId`.
`name`	`string`	The snapshot's name.
`node`	`object`	The Node that holds it. A Box created from it is placed on this Node.
`node.id`	`string`	-
`node.name`	`string`	-
`spec`	`Resources`	The source Box's size, which a Box created from it defaults to.

CubicleOptions

type CubicleOptions = object;

Options for Cubicle. Every field is optional; apiUrl and apiKey fall back to environment variables. A value out of range throws invalid_option.

Properties

Property	Type	Description
`apiKey?`	`string`	A service account API key (`cbk_…`). Defaults to `CB_SDK_API_KEY`.
`apiUrl?`	`string`	The Cubicle API URL, such as `https://api.cubicle.sh`; it must use `http` or `https`. Defaults to `CB_SDK_API_URL`.
`fetch?`	`Fetch`	Replaces the global `fetch`, for proxies or tests.
`maxPollsPerSecond?`	`number`	The most polls per second across all of this client's waits: 0.001 to 1000. Default 5, which keeps many concurrent waits inside the API's rate limit of 600 requests a minute per user or service account. Every API key of one service account shares that limit. See Rate limits
`maxRetries?`	`number`	Retries for rate limits, transient failures and connection failures: 0 to 100. Default 3. Waits ignore it: they retry their reads until their own timeout.
`org?`	`string`	Organization name or ID for `boxes.create`, `boxes.list`, `listBases` and `listSnapshots`, and for narrowing bare Box names. An API key belongs to one organization, which is used when this is omitted.
`pollIntervalMs?`	`number`	How often each wait polls the API, in ms. Default 1 s.
`requestTimeoutMs?`	`number`	Timeout for each attempt of a request, in ms. Default 30 s.

DesiredState

type DesiredState = "running" | "stopped" | "hibernated" | "deleted";

The state a Box was last asked to reach, as BoxInfo.desired reports it.

ExecOptions

type ExecOptions = object;

Options for Boxes.exec.

Properties

Property	Type	Description
`cwd?`	`string`	Absolute working directory in the guest. Defaults to the guest account's home directory.
`idempotencyKey?`	`string`	Makes the request safe to repeat. A new key is generated per call when omitted.
`maxOutputBytes?`	`number`	Cuts stdout and stderr, counted together, at this many bytes. Defaults to 64 KiB, at most 1 MiB.
`signal?`	`AbortSignal`	Stops waiting for the result; the command keeps running.
`timeoutMs?`	`number`	Stops the command after this many ms, at least 100. Defaults to 60 s; larger values are lowered to 10 min. `exec` waits for the result this long plus 2 minutes.
`wake?`	`boolean`	Start a stopped or hibernated Box, and wait until it is ready, before running. A running Box is never restarted.

ExecOutput

type ExecOutput = object;

The result of a completed exec operation.

Properties

Property	Type	Description
`exitCode`	`number`	The command's exit code. A command stopped at its timeout reports 124.
`stderr`	`string`	Standard error, decoded as UTF-8.
`stdout`	`string`	Standard output, decoded as UTF-8.
`timedOut`	`boolean`	The command ran past its `timeoutMs` and was stopped.
`truncated`	`boolean`	Output was cut at `maxOutputBytes`.

ExecResult

type ExecResult = ExecOutput & object;

A finished command. A non-zero exitCode is a result, not an error. operationId is the exec operation's ID.

Type Declaration

Name	Type
`operationId`	`string`

Fetch

type Fetch = (input, init) => Promise<Response>;

A fetch-compatible function, for CubicleOptions.fetch.

Parameters

Parameter	Type
`input`	`string`
`init`	`RequestInit`

Returns

Promise<Response>

LifecycleOptions

type LifecycleOptions = WaitOptions & object;

Options for Boxes.start, Boxes.stop, Boxes.hibernate and Boxes.delete.

Type Declaration

Name	Type	Description
`wait?`	`boolean`	Wait until the Box reaches the requested state. Default `true`. `false` resolves as soon as Cubicle accepts the request.

Me

type Me = object;

The caller, as Cubicle.me returns it.

Properties

Property	Type	Description
`apiKey?`	`object`	Present when an API key authenticated; `orgs` then holds only its organization. A key issued to a connected application has the `application` scope and lists its permissions.
`apiKey.connection?`	`object`	-
`apiKey.connection.applicationId`	`string`	-
`apiKey.connection.id`	`string`	-
`apiKey.connection.permissions`	`string`[]	-
`apiKey.id`	`string`	-
`apiKey.orgId`	`string`	-
`apiKey.scope`	`ApiKeyScope` \| `"application"`	-
`id`	`string`	The user or service account ID.
`identity`	`string`	An email address, or `ORG/NAME` for a service account.
`operator?`	`boolean`	`true` for platform operators.
`orgs`	`object`[]	The organizations the caller belongs to, with its role in each.

Operation

type Operation = object;

A durable exec, snapshot or restore request, as Operations.get returns it.

Properties

Property	Type	Description
`attempt`	`number`	How many times a Node has started it.
`boxId`	`string`	The ID of the Box it acts on.
`completedAt`	`string` \| `null`	When it finished, or `null`.
`createdAt`	`string`	When it was requested, as an ISO 8601 timestamp.
`error`	`string` \| `null`	Why the operation failed, or `null`.
`id`	`string`	The operation's ID, a UUID.
`progress`	`string` \| `null`	A short progress note from the Node while it runs, or `null`.
`result`	`unknown`	For exec, an `ExecOutput`; `null` for another member's exec.
`startedAt`	`string` \| `null`	When a Node started it, or `null`.
`state`	`OperationState`	Where the operation is; see OperationState.
`type`	`"exec"` \| `"snapshot"` \| `"restore"`	What was requested.

OperationOptions

type OperationOptions = WaitOptions & object;

Options for Boxes.snapshot and Boxes.restore.

Type Declaration

Name	Type	Description
`idempotencyKey?`	`string`	Makes the request safe to repeat. A new key is generated per call when omitted.

OperationState

type OperationState = "pending" | "running" | "done" | "failed" | "unknown";

An operation's progress: pending, then running, then done, failed or unknown. unknown means its Node lost track of it, so it may or may not have run.

Readiness

type Readiness = object;

Whether SSH or the console can be used now. When ready is false, reason is the first check that failed, such as not_running or generation_pending; it is null when ready.

Properties

Property	Type
`ready`	`boolean`
`reason`	`string` \| `null`

Resources

type Resources = object;

A Box's size: vcpus virtual CPUs, memoryMiB of memory and diskGiB of disk.

Properties

Property	Type
`diskGiB`	`number`
`memoryMiB`	`number`
`vcpus`	`number`

Snapshot

type Snapshot = object;

A snapshot of one Box's disk, as Boxes.listSnapshots returns it.

Properties

Property	Type	Description
`completedAt`	`string` \| `null`	When it completed, or `null`.
`createdAt`	`string`	When it was requested, as an ISO 8601 timestamp.
`id`	`string`	The snapshot's ID, a UUID. Pass it to `restore`, or to `create` as `snapshotId`.
`name`	`string`	The name given when it was taken. Names need not be unique.
`operationId`	`string`	The snapshot operation that takes it.
`status`	`"pending"` \| `"complete"` \| `"failed"`	`complete` once its operation is done, `failed` if the operation failed.

WaitOptions

type WaitOptions = object;

How long to wait, and how to stop waiting. Every call that waits takes these, except exec, whose timeoutMs is the command's own timeout. The default timeout depends on the call.

See

Waiting

Properties

Property	Type	Description
`signal?`	`AbortSignal`	Stops waiting; the server keeps doing what was requested. The call rejects with the signal's reason.
`timeoutMs?`	`number`	How long to wait before rejecting with `CubicleTimeoutError`. Capped at 2^31 − 1 ms (24.8 days). In ms. A negative value rejects with `invalid_option` when the wait begins.

WaitTarget

type WaitTarget = "ready" | "stopped" | "hibernated";

What waitUntil waits for. ready means SSH and exec can be used now.

ClassesCopy Anchor Link

Type AliasesCopy Anchor Link

ApiKeyScopeCopy Anchor Link

BoxInfoCopy Anchor Link

PropertiesCopy Anchor Link

BoxStateCopy Anchor Link

CreateBoxOptionsCopy Anchor Link

Type DeclarationCopy Anchor Link

CreateBoxParamsCopy Anchor Link

PropertiesCopy Anchor Link

CreationBaseCopy Anchor Link

PropertiesCopy Anchor Link

CreationSnapshotCopy Anchor Link

PropertiesCopy Anchor Link

CubicleOptionsCopy Anchor Link

PropertiesCopy Anchor Link

DesiredStateCopy Anchor Link

ExecOptionsCopy Anchor Link

PropertiesCopy Anchor Link

ExecOutputCopy Anchor Link

PropertiesCopy Anchor Link

ExecResultCopy Anchor Link

Type DeclarationCopy Anchor Link

FetchCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

LifecycleOptionsCopy Anchor Link

Type DeclarationCopy Anchor Link

MeCopy Anchor Link

PropertiesCopy Anchor Link

OperationCopy Anchor Link

PropertiesCopy Anchor Link

OperationOptionsCopy Anchor Link

Type DeclarationCopy Anchor Link

OperationStateCopy Anchor Link

ReadinessCopy Anchor Link

PropertiesCopy Anchor Link

ResourcesCopy Anchor Link

PropertiesCopy Anchor Link

SnapshotCopy Anchor Link

PropertiesCopy Anchor Link

WaitOptionsCopy Anchor Link

SeeCopy Anchor Link

PropertiesCopy Anchor Link

WaitTargetCopy Anchor Link

On this page

Classes

Type Aliases

ApiKeyScope

BoxInfo

Properties

BoxState

CreateBoxOptions

Type Declaration

CreateBoxParams

Properties

CreationBase

Properties

CreationSnapshot

Properties

CubicleOptions

Properties

DesiredState

ExecOptions

Properties

ExecOutput

Properties

ExecResult

Type Declaration

Fetch

Parameters

Returns

LifecycleOptions

Type Declaration

Me

Properties

Operation

Properties

OperationOptions

Type Declaration

OperationState

Readiness

Properties

Resources

Properties

Snapshot

Properties

WaitOptions

See

Properties

WaitTarget