ControlPlane

MicroVM lifecycle by ID (get, list, suspend, resume, terminate, and wait) and image administration (list, delete, versions and their status, builds).

Holds no lifecycle state, so it checks nothing a Sandbox would (STATE-5, STATE-7). Use it when a process has only an identifier.

Accessors

region

Get Signature

get region(): string;

The region this plane addresses.

Returns

string

Methods

deleteImage()

deleteImage(identifier: string, options?: DeleteImageOptions | null): Promise<boolean>;

Deletes the image, its extra versions first, retrying while it refuses (an image still CREATING, or one a terminating VM holds).

Resolves true once the service took the deletion and false when every attempt failed or identifier is not one the service accepts. It doesn’t reject, as a teardown’s delete shouldn’t.

Parameters

Parameter	Type
identifier	string
options?	DeleteImageOptions | null

Returns

Promise<boolean>

---

get()

get(microvmId: string): Promise<Microvm>;

GetMicrovm.

Parameters

Parameter	Type
microvmId	string

Returns

Promise<Microvm>

---

getImageBuild()

getImageBuild(
   identifier: string,
   version: string,
   buildId: string
): Promise<ImageBuild>;

GetMicrovmImageBuild: one build, with the snapshot sizes the listing doesn’t carry.

Parameters

Parameter	Type
identifier	string
version	string
buildId	string

Returns

Promise<ImageBuild>

---

list()

list(options?: ListMicrovmsOptions | null): Promise<MicrovmSummary[]>;

ListMicrovms, every page, optionally narrowed to one image and version.

Parameters

Parameter	Type
options?	ListMicrovmsOptions | null

Returns

Promise<MicrovmSummary[]>

---

listImageBuilds()

listImageBuilds(identifier: string, version: string): Promise<ImageBuild[]>;

ListMicrovmImageBuilds for one version, every page: one build per Graviton generation. Each buildId is what getImageBuild takes.

Parameters

Parameter	Type
identifier	string
version	string

Returns

Promise<ImageBuild[]>

---

listImages()

listImages(): Promise<ImageSummary[]>;

ListMicrovmImages, every page: every image in the account and region.

Returns

Promise<ImageSummary[]>

---

listImageVersions()

listImageVersions(identifier: string): Promise<ImageVersion[]>;

ListMicrovmImageVersions, every page: each version, its status, and its build configuration.

Parameters

Parameter	Type
identifier	string

Returns

Promise<ImageVersion[]>

---

resume()

resume(microvmId: string): Promise<void>;

ResumeMicrovm. Resolves once accepted; waitForState for RUNNING. A VM that ended before the resume, whatever ended it, rejects with ERR_WINDOW_CLOSED (STATE-12).

Parameters

Parameter	Type
microvmId	string

Returns

Promise<void>

---

setImageVersionStatus()

setImageVersionStatus(
   identifier: string,
   version: string,
   status: string
): Promise<ImageVersion>;

UpdateMicrovmImageVersion: status is "ACTIVE" or "INACTIVE".

INACTIVE is the non-destructive retire: RunMicrovm refuses the version, running VMs keep running, and the version’s readback stays. Resolves with the readback, and rejects when it doesn’t carry the status asked for, so a 200 that didn’t take isn’t a rollback.

Parameters

Parameter	Type
identifier	string
version	string
status	string

Returns

Promise<ImageVersion>

---

suspend()

suspend(microvmId: string): Promise<void>;

SuspendMicrovm. Resolves once accepted; waitForState for SUSPENDED.

Parameters

Parameter	Type
microvmId	string

Returns

Promise<void>

---

sweep()

sweep(prefix: string, options?: SweepOptions | null): Promise<SweepReport>;

Discover prefix-matched images and their VMs; set dryRun false to clean them up. Keep entries preserve an exact image name or ARN and every VM using it.

Parameters

Parameter	Type
prefix	string
options?	SweepOptions | null

Returns

Promise<SweepReport>

---

terminate()

terminate(microvmId: string): Promise<void>;

TerminateMicrovm. Resolves once accepted; waitForState for TERMINATED.

Parameters

Parameter	Type
microvmId	string

Returns

Promise<void>

---

waitForState()

waitForState(
   microvmId: string,
   wanted: string[],
   options?: WaitForStateOptions | null
): Promise<Microvm>;

Polls GetMicrovm until the state is one of wanted.

Reaching one of failOn first rejects naming the state and stateReason; running past timeout rejects with a timeout.

Parameters

Parameter	Type
microvmId	string
wanted	string[]
options?	WaitForStateOptions | null

Returns

Promise<Microvm>

---

create()

static create(region: Region, retry?: RetryOptions | null): Promise<ControlPlane>;

Resolves credentials for region from the default chain. A factory because credential resolution is async.

Parameters

Parameter	Type
region	Region
retry?	RetryOptions | null

Returns

Promise<ControlPlane>

Provenance

This page is generated from bindings/microvms-js/index.d.ts by TypeDoc 0.28.20 and typedoc-plugin-markdown 4.13.1, run from site/scripts/gen-reference.mjs on every pnpm run sync, so an edit made here is overwritten by the next run.

To change the page, change the doc comment in the binding’s Rust source, then regenerate the declarations with mise run dts. mise run dts:check fails when the committed file no longer matches the source.