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

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

```ts
get region(): string;
```

The region this plane addresses.

##### Returns

`string`

## Methods

### deleteImage()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/deleteimageoptions/) | `null` |

#### Returns

`Promise`\<`boolean`>

***

### get()

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

`GetMicrovm`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `microvmId` | `string` |

#### Returns

`Promise`\<[`Microvm`](/microvms-agentd/reference/typescript/interfaces/microvm/)>

***

### getImageBuild()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/imagebuild/)>

***

### list()

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

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`ListMicrovmsOptions`](/microvms-agentd/reference/typescript/interfaces/listmicrovmsoptions/) | `null` |

#### Returns

`Promise`\<[`MicrovmSummary`](/microvms-agentd/reference/typescript/interfaces/microvmsummary/)\[]>

***

### listImageBuilds()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/imagebuild/)\[]>

***

### listImages()

```ts
listImages(): Promise<ImageSummary[]>;
```

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

#### Returns

`Promise`\<[`ImageSummary`](/microvms-agentd/reference/typescript/interfaces/imagesummary/)\[]>

***

### listImageVersions()

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

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `identifier` | `string` |

#### Returns

`Promise`\<[`ImageVersion`](/microvms-agentd/reference/typescript/interfaces/imageversion/)\[]>

***

### resume()

```ts
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()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/imageversion/)>

***

### suspend()

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

`SuspendMicrovm`. Resolves once accepted; `waitForState` for SUSPENDED.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `microvmId` | `string` |

#### Returns

`Promise`\<`void`>

***

### sweep()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/sweepoptions/) | `null` |

#### Returns

`Promise`\<[`SweepReport`](/microvms-agentd/reference/typescript/interfaces/sweepreport/)>

***

### terminate()

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

`TerminateMicrovm`. Resolves once accepted; `waitForState` for TERMINATED.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `microvmId` | `string` |

#### Returns

`Promise`\<`void`>

***

### waitForState()

```ts
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`](/microvms-agentd/reference/typescript/interfaces/waitforstateoptions/) | `null` |

#### Returns

`Promise`\<[`Microvm`](/microvms-agentd/reference/typescript/interfaces/microvm/)>

***

### create()

```ts
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`](/microvms-agentd/reference/typescript/classes/region/) |
| `retry?` | [`RetryOptions`](/microvms-agentd/reference/typescript/interfaces/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.