---
title: "microvms: functions, constants, and enums"
description: The module-level functions, constants, and enums of the microvms npm package.
---

Everything `microvms` exports that is not a class or an interface of its own. Import any of them by name from the package.

## Enumerations

### GapPolicy

What to do when the daemon reports evicted output.

A string union rather than an enum class, because napi renders `#[napi(string_enum)]` as a
TypeScript union of literals — `'error' | 'event'`, which is what a JS caller writes anyway
— and there is no closure here to protect (see `lib.rs` on when a class is required
instead).

#### Enumeration Members

##### Error

```ts
Error: "error";
```

**The default.** A gap errors both streams, with the lost range in the message. See the
module docs for why an error rather than an ignorable event.

##### Event

```ts
Event: "event";
```

A gap is recorded on \[`ExecProcess::gaps`] and both streams stay open.

For a caller that wants the surviving bytes more than the completeness guarantee. The
consumer is then responsible for reading `gaps`, and nothing forces it to.

## Variables

### \_\_napiBindingTarget

```ts
const __napiBindingTarget: "native" | "wasm32-wasi" | "wasm32-wasip1";
```

Which binding artifact the generated loader actually loaded: `'native'` for
a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
can point the loader at a WASI artifact this package does not build itself.

## Functions

### agentConstants()

```ts
function agentConstants(): string;
```

The layer's fixed values as JSON, for a caller that wants to reason about the guest.

#### Returns

`string`

***

### baseImageFromDockerfile()

```ts
function baseImageFromDockerfile(dockerfile: string): BaseImageInput;
```

The base a task Dockerfile pairs with: the managed base's `name`, so `baseImageArn` is
unchanged, and the Dockerfile's first `FROM` as `dockerRef`, digest pin included.

`buildImage` refuses a Dockerfile whose first `FROM` is not the base's `dockerRef`; a base
derived from that Dockerfile passes by construction. Throws `ERR_INVALID_ARG` for a
Dockerfile with no `FROM`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `dockerfile` | `string` |

#### Returns

[`BaseImageInput`](/microvms-agentd/reference/typescript/interfaces/baseimageinput/)

***

### buildUnpricedReason()

```ts
function buildUnpricedReason(): string;
```

Why the image build has no price, as the reason that lands on the line item.

#### Returns

`string`

***

### checkBudget()

```ts
function checkBudget(
   report: CostReport, 
   maxUsd: string, 
   onBreach: string
): BudgetVerdict;
```

Judges `report`'s total against a ceiling of `maxUsd` (a decimal string, such as `"1.50"`),
with `onBreach` (`"warn"` or `"abort"`) saying what a breach does.

`onBreach` has no default, because a breach of a lower-bound total has already been exceeded
by an unknown margin, and whether that warns or refuses is the caller's call. Core's
`Budget::check`, the gate `microvm cost --max-cost` applies.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `report` | [`CostReport`](/microvms-agentd/reference/typescript/classes/costreport/) |
| `maxUsd` | `string` |
| `onBreach` | `string` |

#### Returns

[`BudgetVerdict`](/microvms-agentd/reference/typescript/classes/budgetverdict/)

***

### compareResidency()

```ts
function compareResidency(
   size: SizeClass, 
   holdSeconds: number, 
   cycles?: number | null, 
   rates?: RateTable | null
): ResidencyComparison;
```

The warm-pool argument, with its own counter-argument attached.

Leave `cycles` out and the comparison prices one suspend/resume cycle, the core's default
and the one `microvm cost --compare` applies: the per-cycle figure is what keeps the
argument honest. A report's `suspendResumeCycles` defaults to none instead.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `size` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) |
| `holdSeconds` | `number` |
| `cycles?` | `number` | `null` |
| `rates?` | [`RateTable`](/microvms-agentd/reference/typescript/classes/ratetable/) | `null` |

#### Returns

[`ResidencyComparison`](/microvms-agentd/reference/typescript/classes/residencycomparison/)

***

### coreVersion()

```ts
function coreVersion(): string;
```

The core crate's version, for a `doctor` or `manifest` command to report.

The **core's** version and not this crate's: what a caller needs to know is which client
they are talking through, and a binding version that drifted from it would be a second
number nobody can act on.

#### Returns

`string`

***

### costConstants()

```ts
function costConstants(): string;
```

The documented cost constants, as a JSON string a caller can assert against.

A JSON string rather than a typed object because it is a transcription of published
facts whose shape may grow, and a `#[napi(object)]` would make every addition a
signature change.

#### Returns

`string`

***

### defaultBaseImage()

```ts
function defaultBaseImage(): BaseImageInput;
```

The managed Amazon Linux 2023 base used for measurements in `docs/PLATFORM.md`.

#### Returns

[`BaseImageInput`](/microvms-agentd/reference/typescript/interfaces/baseimageinput/)

***

### egressPostureFor()

```ts
function egressPostureFor(
   egress?: boolean | null, 
   connectors?: string[] | null, 
   denyEgress?: boolean | null, 
   region?: Region | null
): string;
```

The egress posture `sandbox.run` with these options would report, without launching.

One of `"open"`, `"unsealed"`, `"best-effort"`, or `"sealed"`: the value the launched
session's `egressPosture()` and the CLI envelope's `egressPosture` carry. Throws the launch's
own `ERR_INVALID_ARG` for options it would refuse. No AWS call and no credentials, so a
harness can decide before a build whether a no-network task is satisfiable.

Only `"sealed"` is network isolation, and no option answers it: isolation needs a VPC
egress connector and separately verified VPC routing without an internet gateway or NAT
gateway. Omitting `egress` is `"unsealed"`; `denyEgress` is `"best-effort"`. Without a
`region`, each connector ARN is checked against the region it names.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `egress?` | `boolean` | `null` |
| `connectors?` | `string`\[] | `null` |
| `denyEgress?` | `boolean` | `null` |
| `region?` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) | `null` |

#### Returns

`string`

***

### errorCodes()

```ts
function errorCodes(): string[];
```

Every `ERR_*` code this library can raise, for a caller building an exhaustive switch.

Enumerated from the core's own `ErrorKind::ALL` rather than transcribed, so a kind added
there appears here without an edit — a hand-written list would agree with a typo.

#### Returns

`string`\[]

***

### estimateRun()

```ts
function estimateRun(
   size: SizeClass, 
   options?: PlanUsageOptions | null, 
   rates?: RateTable | null
): CostReport;
```

What a plan will cost, before spending anything (COST-10).

Takes plain seconds and marks every one projected. That is the difference from
\[`run_report`]: not the arithmetic, which is shared, but what the durations admit about
themselves.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `size` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) |
| `options?` | [`PlanUsageOptions`](/microvms-agentd/reference/typescript/interfaces/planusageoptions/) | `null` |
| `rates?` | [`RateTable`](/microvms-agentd/reference/typescript/classes/ratetable/) | `null` |

#### Returns

[`CostReport`](/microvms-agentd/reference/typescript/classes/costreport/)

***

### installAgentAccess()

```ts
function installAgentAccess(
   session: Session, 
   agents: AgentSpecInput[], 
   token: BearerToken
): Promise<void>;
```

Installs Bedrock access for `agents` into a running VM over `session`.

Three uploads (the environment file, Codex's config when Codex is among the agents, the
marker) and one root `chown` of `/workspace` to uid 1000. Re-runnable: a fresh token
overwrites the same files, which is how a twelve-hour token is refreshed.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `session` | [`Session`](/microvms-agentd/reference/typescript/classes/session/) |
| `agents` | [`AgentSpecInput`](/microvms-agentd/reference/typescript/interfaces/agentspecinput/)\[] |
| `token` | [`BearerToken`](/microvms-agentd/reference/typescript/classes/bearertoken/) |

#### Returns

`Promise`\<`void`>

***

### installedAgents()

```ts
function installedAgents(session: Session): Promise<AgentSpec[]>;
```

The agents a running VM was provisioned with, read from its guest marker.

For a process holding only a session (`Session.direct` from the identifier triple): how a
credential refresh learns which agents and models to re-provision. A VM with no marker is
refused as a precondition, naming `agent-up`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `session` | [`Session`](/microvms-agentd/reference/typescript/classes/session/) |

#### Returns

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

***

### isRetryable()

```ts
function isRetryable(error: unknown): boolean;
```

Whether retrying the identical call could plausibly succeed, for an error this library raised.

The TypeScript spelling of Python's `.retryable`, read off the chain every error here
carries: `err.cause.message` is the `ERR_*` code, and core answers for its kind. A
transient condition (a refused connection, a mint failure, a daemon not yet bootstrapped)
is `true`; a full disk, a credential, or a refused argument is `false`. Anything that
isn't a library error (no cause, or a cause whose message is no `ERR_*` code) is `false`,
because nothing says a retry would land differently.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `error` | `unknown` |

#### Returns

`boolean`

***

### mintBedrockToken()

```ts
function mintBedrockToken(region: Region, ttlSeconds?: number | null): Promise<BearerToken>;
```

Mints a Bedrock bearer token from the default credential chain.

A SigV4 presign of `POST https://bedrock.amazonaws.com/?Action=CallWithBearerToken`,
base64, prefixed `bedrock-api-key-` — the reference generator's recipe, in process.
`ttlSeconds` defaults to the ceiling, twelve hours; more is refused by the core.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) |
| `ttlSeconds?` | `number` | `null` |

#### Returns

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

***

### mintBedrockTokenWithCredentials()

```ts
function mintBedrockTokenWithCredentials(
   region: Region, 
   accessKeyId: string, 
   secretAccessKey: string, 
   sessionToken: string | null | undefined, 
   credentialsExpiresAt: number, 
   ttlSeconds?: number | null
): BearerToken;
```

Mint using explicit STS credentials without changing the process environment.
credentialsExpiresAt is Unix seconds from STS Expiration. Do not log these inputs.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) |
| `accessKeyId` | `string` |
| `secretAccessKey` | `string` |
| `sessionToken` | `string` | `null` | `undefined` |
| `credentialsExpiresAt` | `number` |
| `ttlSeconds?` | `number` | `null` |

#### Returns

[`BearerToken`](/microvms-agentd/reference/typescript/classes/bearertoken/)

***

### preflight()

```ts
function preflight(region?: Region | null): Promise<PreflightReport>;
```

Whether a harness can launch in `region` (default: `$AWS_REGION`, `$AWS_DEFAULT_REGION`,
then us-east-1), checked before it queues work.

Three checks: the region resolves (advisory outside `Region.measured()`), the credential chain
resolves credentials (no AWS call), and one `ListManagedMicrovmImages` page answers in that
region, the only AWS operation, free and read-only. A check after a failure is reported
with `ran: false` and makes no call. Nothing billable, nothing mutating. It does not check
roles, the artifact bucket, quotas, or VPC connectors. Never rejects; read `report.ok`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `region?` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) | `null` |

#### Returns

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

***

### promptAgent()

```ts
function promptAgent(
   session: Session, 
   agent: AgentSpecInput, 
   task: string, 
   options?: PromptOptions | null
): Promise<ExecHandle>;
```

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

#### Parameters

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

#### Returns

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

***

### provisionAgentd()

```ts
function provisionAgentd(options?: ProvisionOptions | null): Promise<Buffer<ArrayBufferLike>>;
```

The `agentd` daemon binary for `options.version` (default: this client's own).

Answered from `options.binary` or `$MICROVM_AGENTD` when either names a file, else the
version's cache entry, else the GitHub release asset, verified in-process against the
release workflow's Sigstore attestation or, only when GitHub can't be reached for one, the
release's `SHA256SUMS`. A fetch that cannot be verified rejects with `ERR_PRECONDITION`
(on `err.cause.message`), and so does any binary that is not an aarch64 ELF. Neither
`gh` nor `curl` is needed.

#### Parameters

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

#### Returns

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

***

### provisionAgentdReport()

```ts
function provisionAgentdReport(options?: ProvisionOptions | null): Promise<ProvisionedAgentd>;
```

`provisionAgentd`, answering with the bytes and how they got here.

#### Parameters

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

#### Returns

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

***

### retryDetails()

```ts
function retryDetails(error: unknown): RetryDetails | null;
```

Reads typed telemetry from a control-plane rejection, or returns null for other errors.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `error` | `unknown` |

#### Returns

[`RetryDetails`](/microvms-agentd/reference/typescript/interfaces/retrydetails/) | `null`

***

### runReport()

```ts
function runReport(
   size: SizeClass, 
   options?: RunUsageOptions | null, 
   rates?: RateTable | null
): CostReport;
```

Per-phase attribution for one sandbox's lifecycle.

Every duration is a \[`Duration`] class and not a number, which is what keeps the
provenance label attached: taking seconds here would need this function to pick a
provenance, and the one it would pick is the stronger claim.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `size` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) |
| `options?` | [`RunUsageOptions`](/microvms-agentd/reference/typescript/interfaces/runusageoptions/) | `null` |
| `rates?` | [`RateTable`](/microvms-agentd/reference/typescript/classes/ratetable/) | `null` |

#### Returns

[`CostReport`](/microvms-agentd/reference/typescript/classes/costreport/)

***

### sessionConstants()

```ts
function sessionConstants(): string;
```

The daemon's protocol constants, as a JSON string, for a caller asserting against the
wire contract.

#### Returns

`string`

***

### wireKinds()

```ts
function wireKinds(): string[];
```

Every daemon-status class, as `err.cause.cause.message` names them.

#### Returns

`string`\[]

***

### wrapDockerfile()

```ts
function wrapDockerfile(taskDockerfile: string, options?: WrapDockerfileOptions | null): string;
```

A task Dockerfile with the agentd stanza appended, ready for `buildImage`.

The result is the task text, a newline if it lacked one, `USER root` when the task's last
`USER` is anyone else, then the stanza the default Dockerfile uses: `COPY agentd /agentd`,
the chmod, `ENV AGENTD_PORT`, `EXPOSE`, `ENTRYPOINT []` and `CMD ["/agentd"]`. Pass the
result to `buildImage` with `baseImage: baseImageFromDockerfile(result)`.

Throws `ERR_INVALID_ARG` for a task with no `FROM`, one that ends inside a line
continuation or an unterminated heredoc (either would swallow the stanza), a keepalive the
client cannot tolerate, a port of 0, a workdir that is not one absolute path, or
`inheritWorkdir` with nothing to inherit.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `taskDockerfile` | `string` |
| `options?` | [`WrapDockerfileOptions`](/microvms-agentd/reference/typescript/interfaces/wrapdockerfileoptions/) | `null` |

#### Returns

`string`

***

### wrapDockerfilePreservingUser()

```ts
function wrapDockerfilePreservingUser(taskDockerfile: string, options?: WrapDockerfileOptions | null): string;
```

Preserve the final Dockerfile USER's uid and primary gid as the workload default.
The builder resolves stage inheritance, variables and names. Explicit image
AGENTD\_DEFAULT\_USER and request users win. The daemon starts as root and
workloads start only after readiness. Requires COPY --chmod.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `taskDockerfile` | `string` |
| `options?` | [`WrapDockerfileOptions`](/microvms-agentd/reference/typescript/interfaces/wrapdockerfileoptions/) | `null` |

#### Returns

`string`

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