AgentVm

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

agents(): AgentSpec[];

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

Returns

AgentSpec[]

---

buildArtifact()

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
size?	SizeClass | null

Returns

Promise<Buffer<ArrayBufferLike>>

---

buildImage()

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
size?	SizeClass | null

Returns

Promise<Image>

---

detach()

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>

---

dockerfile()

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

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
size?	SizeClass | null

Returns

Promise<EnsuredImage>

---

findImage()

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
size?	SizeClass | null

Returns

Promise<string | null>

---

imageName()

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
size?	SizeClass | null

Returns

Promise<string>

---

installAccess()

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 | null
ttlSeconds?	number | null

Returns

Promise<BearerToken>

---

launch()

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

Returns

Promise<Session>

---

prompt()

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 | null

Returns

Promise<ExecHandle>

---

promptSync()

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 | null

Returns

Promise<ExecResult>

---

region()

region(): Region;

Returns

Region

---

sandbox()

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

---

session()

session(): Promise<Session | null>;

The session, once launch has resolved.

Returns

Promise<Session | null>

---

terminate()

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

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

Parameters

Parameter	Type
options?	TeardownOptions | null

Returns

Promise<TeardownReport>

---

adopt()

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
microvmId	string
endpoint	string
agentToken	string
agents?	AgentSpecInput[] | null
port?	number | null

Returns

Promise<AgentVm>

---

create()

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
agents?	AgentSpecInput[] | null

Returns

Promise<AgentVm>

---

fromName()

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
name	string
registry	NameRegistry
agents?	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.