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

```python
@final
class 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): a
suspend of a SUSPENDED VM is the service's to refuse. Use it when a process has only an
identifier, such as a durable workflow step in a fresh process.

## Constructor

```python
ControlPlane(
    region: Region,
    *,
    retry: tuple[SupportsIndex, SupportsFloat | SupportsIndex] | None = None,
)
```

Resolves credentials for `region` from the default chain.

## Properties

### `region`

```python
region: Region
```

The region this plane addresses.

## Methods

### `create_async`

```python
@staticmethod
def create_async(
    region: Region,
    *,
    retry: tuple[SupportsIndex, SupportsFloat | SupportsIndex] | None = None,
) -> ControlPlane
```

The awaitable twin of `ControlPlane(region)`.

### `delete_image`

```python
def delete_image(
    identifier: str,
    *,
    attempts: SupportsIndex | None = None,
    backoff: SupportsFloat | SupportsIndex | None = None,
) -> bool
```

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

Returns `True` once the service took the deletion and `False` when every attempt failed
or `identifier` is not one the service accepts. It doesn't raise, as a teardown's delete
shouldn't. `attempts` and `backoff` (seconds) default to the core's teardown figures.

### `delete_image_async`

```python
def delete_image_async(
    identifier: str,
    *,
    attempts: SupportsIndex | None = None,
    backoff: SupportsFloat | SupportsIndex | None = None,
) -> bool
```

The awaitable twin of `delete_image`. A lifecycle call: cancelling the awaitable leaves
the deletion and its retries running to their answer.

### `get`

```python
def get(microvm_id: str) -> Microvm
```

`GetMicrovm`.

### `get_async`

```python
def get_async(microvm_id: str) -> Microvm
```

The awaitable twin of `get`.

### `get_image_build`

```python
def get_image_build(identifier: str, version: str, build_id: str) -> ImageBuild
```

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

### `get_image_build_async`

```python
def get_image_build_async(identifier: str, version: str, build_id: str) -> ImageBuild
```

The awaitable twin of `get_image_build`.

### `list`

```python
def list(
    *,
    image_identifier: str | None = None,
    image_version: str | None = None,
) -> list[MicrovmSummary]
```

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

### `list_async`

```python
def list_async(
    *,
    image_identifier: str | None = None,
    image_version: str | None = None,
) -> list[MicrovmSummary]
```

The awaitable twin of `list`.

### `list_image_builds`

```python
def list_image_builds(identifier: str, version: str) -> list[ImageBuild]
```

`ListMicrovmImageBuilds` for one version, every page: one build per Graviton
generation. Each `build_id` is what `get_image_build` takes.

### `list_image_builds_async`

```python
def list_image_builds_async(identifier: str, version: str) -> list[ImageBuild]
```

The awaitable twin of `list_image_builds`.

### `list_image_versions`

```python
def list_image_versions(identifier: str) -> list[ImageVersion]
```

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

### `list_image_versions_async`

```python
def list_image_versions_async(identifier: str) -> list[ImageVersion]
```

The awaitable twin of `list_image_versions`.

### `list_images`

```python
def list_images() -> list[ImageSummary]
```

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

### `list_images_async`

```python
def list_images_async() -> list[ImageSummary]
```

The awaitable twin of `list_images`.

### `resume`

```python
def resume(microvm_id: str) -> None
```

`ResumeMicrovm`. Returns once accepted; `wait_for_state` for RUNNING. A VM that ended
before the resume, whatever ended it, raises `WindowClosedError` (STATE-12).

### `resume_async`

```python
def resume_async(microvm_id: str) -> None
```

The awaitable twin of `resume`. A lifecycle call, as `suspend_async` is.

### `set_image_version_status`

```python
def set_image_version_status(identifier: str, version: str, status: str) -> 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. Returns the readback, and raises when it
doesn't carry the status asked for, so a 200 that didn't take isn't a rollback.

### `set_image_version_status_async`

```python
def set_image_version_status_async(
    identifier: str,
    version: str,
    status: str,
) -> ImageVersion
```

The awaitable twin of `set_image_version_status`. A lifecycle call: cancelling the
awaitable leaves the update running to its readback.

### `suspend`

```python
def suspend(microvm_id: str) -> None
```

`SuspendMicrovm`. Returns once accepted; `wait_for_state` for SUSPENDED.

### `suspend_async`

```python
def suspend_async(microvm_id: str) -> None
```

The awaitable twin of `suspend`. A lifecycle call: cancelling the awaitable leaves the
request running to its answer.

### `sweep`

```python
def sweep(
    prefix: str,
    *,
    keep: SupportsGetItem[int, str] | None = None,
    dry_run: bool | None = None,
) -> SweepReport
```

Discover prefix-matched images and VMs. Set dry\_run=False to clean them up.
Keep entries preserve exact image names or ARNs and every VM using them.

### `sweep_async`

```python
def sweep_async(
    prefix: str,
    *,
    keep: SupportsGetItem[int, str] | None = None,
    dry_run: bool | None = None,
) -> SweepReport
```

The awaitable twin of sweep. Once cleanup starts, cancellation leaves it running.

### `terminate`

```python
def terminate(microvm_id: str) -> None
```

`TerminateMicrovm`. Returns once accepted; `wait_for_state` for TERMINATED.

### `terminate_async`

```python
def terminate_async(microvm_id: str) -> None
```

The awaitable twin of `terminate`. A lifecycle call, as `suspend_async` is.

### `wait_for_state`

```python
def wait_for_state(
    microvm_id: str,
    wanted: SupportsGetItem[int, str],
    *,
    fail_on: SupportsGetItem[int, str] | None = None,
    timeout: SupportsFloat | SupportsIndex = 300.0,
    poll_interval: SupportsFloat | SupportsIndex = 5.0,
) -> Microvm
```

Polls `GetMicrovm` until the state is one of `wanted`.

Reaching one of `fail_on` first raises `LaunchDiedError` naming the state and
`stateReason`; running past `timeout` raises `TimeoutError`.

### `wait_for_state_async`

```python
def wait_for_state_async(
    microvm_id: str,
    wanted: SupportsGetItem[int, str],
    *,
    fail_on: SupportsGetItem[int, str] | None = None,
    timeout: SupportsFloat | SupportsIndex = 300.0,
    poll_interval: SupportsFloat | SupportsIndex = 5.0,
) -> Microvm
```

The awaitable twin of `wait_for_state`. Cancelling it stops the polling and touches no
VM.

## Special methods

### `__repr__`

```python
def __repr__() -> str
```

## Provenance

This page is generated from `bindings/microvms-py/microvms.pyi` by Griffe 2.3.0, 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 stubs`. `mise run stubs:check` fails when the committed file no longer matches the source.