---
title: AgentVm
description: "One VM with coding agents in it: the sandbox plus the specs it is built for."
---

One VM with coding agents in it: the sandbox plus the specs it is built for.

The sequence is the CLI's `agent-up` and `agent-prompt`, one method per step: `findImage`
or `buildArtifact` + your upload + `buildImage`; `launch`; `installAccess`; `prompt` or
`promptSync`; `terminate`. `sandbox()` and `session()` reach the same VM for suspend,
resume, file transfer, and any other exec.

## Methods

### agents()

```ts
agents(): AgentSpec[];
```

The specs this VM carries, resolved, in profile order.

#### Returns

[`AgentSpec`](/microvms-agentd/reference/typescript/interfaces/agentspec/)\[]

***

### buildArtifact()

```ts
buildArtifact(options: AgentImageOptions, size?: SizeClass | null): Promise<Buffer<ArrayBufferLike>>;
```

The artifact bytes to upload to `s3://<bucket>/<imageName>.zip` before `buildImage`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentImageOptions`](/microvms-agentd/reference/typescript/interfaces/agentimageoptions/) |
| `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` |

#### Returns

`Promise`\<`Buffer`\<`ArrayBufferLike`>>

***

### buildImage()

```ts
buildImage(options: AgentImageOptions, size?: SizeClass | null): Promise<Image>;
```

Builds the image and waits for it to become usable. `codeArtifactUri` is where you
uploaded `buildArtifact`'s bytes. Several minutes, server-side.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentImageOptions`](/microvms-agentd/reference/typescript/interfaces/agentimageoptions/) |
| `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` |

#### Returns

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

***

### detach()

```ts
detach(): Promise<Detached>;
```

Hands the VM off to another process; see `Sandbox.detach`. The adopter passes the
same agents to `AgentVm.adopt`.

#### Returns

`Promise`\<[`Detached`](/microvms-agentd/reference/typescript/classes/detached/)>

***

### dockerfile()

```ts
dockerfile(): Promise<string>;
```

The Dockerfile `buildImage` will send: the client's agentd stanza plus the agent
layers. Nothing in it is a secret.

#### Returns

`Promise`\<`string`>

***

### ensureImage()

```ts
ensureImage(options: AgentEnsureOptions, size?: SizeClass | null): Promise<EnsuredImage>;
```

Builds or reuses this VM's image, named per `imageName`: resolved at once when ready,
waited on while building, deleted and rebuilt when failed, and uploaded to
`s3://<s3Bucket>/<s3KeyPrefix>/<name>/artifact.zip` only when a build is needed.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentEnsureOptions`](/microvms-agentd/reference/typescript/interfaces/agentensureoptions/) |
| `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` |

#### Returns

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

***

### findImage()

```ts
findImage(options: AgentImageOptions, size?: SizeClass | null): Promise<string | null>;
```

The ARN of an existing image named per `imageName`, or `null` when there is none.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentImageOptions`](/microvms-agentd/reference/typescript/interfaces/agentimageoptions/) |
| `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` |

#### Returns

`Promise`\<`string` | `null`>

***

### imageName()

```ts
imageName(options: AgentImageOptions, size?: SizeClass | null): Promise<string>;
```

The image name for these specs and this daemon binary: `agent-vm-<agents>-<hash12>`.
Content-addressed, so an unchanged binary, spec set and size name the image a previous
run built; `findImage` looks it up, and `ensureImage` builds or reuses it.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentImageOptions`](/microvms-agentd/reference/typescript/interfaces/agentimageoptions/) |
| `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` |

#### Returns

`Promise`\<`string`>

***

### installAccess()

```ts
installAccess(token?: BearerToken | null, ttlSeconds?: number | null): Promise<BearerToken>;
```

Mints a token (or takes yours) and installs Bedrock access for this VM's agents.

Resolves with the token used, so `expiresAt` says when to call this again. Re-runnable
on a running VM: that call is the credential refresh.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `token?` | [`BearerToken`](/microvms-agentd/reference/typescript/classes/bearertoken/) | `null` |
| `ttlSeconds?` | `number` | `null` |

#### Returns

`Promise`\<[`BearerToken`](/microvms-agentd/reference/typescript/classes/bearertoken/)>

***

### launch()

```ts
launch(options: AgentLaunchOptions): Promise<Session>;
```

Launches with egress and waits for the daemon to answer.

Egress is not optional: neither agent reaches Bedrock without it. The managed internet
connector is the default; `egressNetworkConnectors` replaces it with customer-managed
VPC connectors, whose VPC must route to Bedrock. The idle knobs default to the core's
figures (ten-minute idle and suspended windows, a one-hour ceiling).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`AgentLaunchOptions`](/microvms-agentd/reference/typescript/interfaces/agentlaunchoptions/) |

#### Returns

`Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/)>

***

### prompt()

```ts
prompt(
   agent: string, 
   task: string, 
   options?: PromptOptions | null
): Promise<ExecHandle>;
```

Starts one task for `agent` and resolves with its handle. Does not wait.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `agent` | `string` |
| `task` | `string` |
| `options?` | [`PromptOptions`](/microvms-agentd/reference/typescript/interfaces/promptoptions/) | `null` |

#### Returns

`Promise`\<[`ExecHandle`](/microvms-agentd/reference/typescript/classes/exechandle/)>

***

### promptSync()

```ts
promptSync(
   agent: string, 
   task: string, 
   options?: PromptOptions | null
): Promise<ExecResult>;
```

Start, wait, ack: one task's whole result. `timeoutSec` defaults to 900 seconds,
because agent tasks run minutes, and is also the daemon-side budget.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `agent` | `string` |
| `task` | `string` |
| `options?` | [`PromptOptions`](/microvms-agentd/reference/typescript/interfaces/promptoptions/) | `null` |

#### Returns

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

***

### region()

```ts
region(): Region;
```

#### Returns

[`Region`](/microvms-agentd/reference/typescript/classes/region/)

***

### sandbox()

```ts
sandbox(): Sandbox;
```

The sandbox this VM drives, for suspend, resume, and the lifecycle getters. The same
lock: a call here and a call there cannot interleave.

#### Returns

[`Sandbox`](/microvms-agentd/reference/typescript/classes/sandbox/)

***

### session()

```ts
session(): Promise<Session | null>;
```

The session, once `launch` has resolved.

#### Returns

`Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/) | `null`>

***

### terminate()

```ts
terminate(options?: TeardownOptions | null): Promise<TeardownReport>;
```

Tears down, best-effort, never rejecting; see `Sandbox.terminate`.

#### Parameters

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

#### Returns

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

***

### adopt()

```ts
static adopt(
   region: Region, 
   microvmId: string, 
   endpoint: string, 
   agentToken: string, 
   agents?: AgentSpecInput[] | null, 
   port?: number | null
): Promise<AgentVm>;
```

An agent VM for a VM another process launched; see `Sandbox.adopt`.

`agents` states what the VM carries and defaults to Claude Code alone; read
`installedAgents(session)` first when the adopting process does not know.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) |
| `microvmId` | `string` |
| `endpoint` | `string` |
| `agentToken` | `string` |
| `agents?` | [`AgentSpecInput`](/microvms-agentd/reference/typescript/interfaces/agentspecinput/)\[] | `null` |
| `port?` | `number` | `null` |

#### Returns

`Promise`\<`AgentVm`>

***

### create()

```ts
static create(region: Region, agents?: AgentSpecInput[] | null): Promise<AgentVm>;
```

Resolves credentials for `region` and returns a VM with nothing built or launched.

`agents` defaults to Claude Code alone. An empty list or a repeated agent is refused by
the core before any AWS call.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) |
| `agents?` | [`AgentSpecInput`](/microvms-agentd/reference/typescript/interfaces/agentspecinput/)\[] | `null` |

#### Returns

`Promise`\<`AgentVm`>

***

### fromName()

```ts
static fromName(
   region: Region, 
   name: string, 
   registry: NameRegistry, 
   agents?: AgentSpecInput[] | null, 
   port?: number | null
): Promise<AgentVm>;
```

Adopts the agent VM registered as `name` in `registry`; see `Sandbox.fromName`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) |
| `name` | `string` |
| `registry` | [`NameRegistry`](/microvms-agentd/reference/typescript/classes/nameregistry/) |
| `agents?` | [`AgentSpecInput`](/microvms-agentd/reference/typescript/interfaces/agentspecinput/)\[] | `null` |
| `port?` | `number` | `null` |

#### Returns

`Promise`\<`AgentVm`>

## 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.