---
title: TypeScript SDK
description: Install the microvms npm package, run a first command, and find every class, interface, function, and enum it exports.
---

The `microvms` package on npm, for Node.js from JavaScript or TypeScript. This reference is generated from `bindings/microvms-js/index.d.ts`, the declaration file the package ships, so a signature here is the one your editor and `tsc` see.

## Install

```sh
npm install microvms
```

Requires Node.js **22.13.0+**. Native addons ship for Linux x64/ARM64 (glibc),
macOS Apple Silicon, and Windows x64. TypeScript declarations are included.

## Run your first command

This example starts a VM from an image, runs a command, and cleans up.
Set up AWS and build the image first. Each launch creates resources that
AWS bills to your account.

You need Lambda MicroVMs access, your normal AWS credential configuration,
and an execution role. Follow [AWS setup](/microvms-agentd/learn/tutorial/first-run/)
to set `AWS_REGION` and `MICROVM_EXECUTION_ROLE_ARN`. Then use the
[CLI](/microvms-agentd/learn/tutorial/install/)
to prepare an image containing `agentd`:

```sh
microvm build --name agent-tools --json
export MICROVM_IMAGE='paste data.imageIdentifier from the result'
```

Use the **image ARN**, in the same account and region as your credentials.
The SDK can also look up an image by name in that region. This example uses
the ARN returned by the build.
The CLI provisions `agentd` and uploads the build artifact for you.
Shell examples use Bash or Zsh; in PowerShell, set variables with `$env:NAME='value'`.

Save as `hello.mjs`:

```js
import { Region, Sandbox } from 'microvms';

const imageIdentifier = process.env.MICROVM_IMAGE;
const executionRoleArn = process.env.MICROVM_EXECUTION_ROLE_ARN;
if (!imageIdentifier || !executionRoleArn) {
  throw new Error('Set MICROVM_IMAGE and MICROVM_EXECUTION_ROLE_ARN first');
}
const vm = await Sandbox.create(Region.parse(process.env.AWS_REGION ?? 'us-east-1'));
try {
  const session = await vm.run({ imageIdentifier, executionRoleArn });
  const result = await session.runSync(['echo', 'hello from a sandbox']);
  process.stdout.write(result.stdout);
  process.stderr.write(result.stderr);
  if (!result.ok) process.exitCode = 1;
} finally {
  const cleanup = await vm.terminate();
  if (cleanup.failures.length || cleanup.undeleted.length) {
    console.error('Cleanup needs attention:', cleanup);
    process.exitCode = 1;
  }
}
```

```sh
node hello.mjs
```

Expected output: `hello from a sandbox`. The VM is terminated after the
command; the image stays available for reuse. `terminate()` returns once
termination is accepted by default. Pass `{ waitForTerminated: true }` to
wait for the final state. Inspect `failures` and `undeleted` because cleanup
reports failures in its result.

## Everything the package exports

Each class and interface has its own page. Functions, constants, and enums share [one page](/microvms-agentd/reference/typescript/module/).

| Name | Kind | Summary |
| --- | --- | --- |
| [`AgentVm`](/microvms-agentd/reference/typescript/classes/agentvm/) | class | One VM with coding agents in it: the sandbox plus the specs it is built for. |
| [`Amount`](/microvms-agentd/reference/typescript/classes/amount/) | class | What a line item's cost can be: an estimate, or unpriced. |
| [`BearerToken`](/microvms-agentd/reference/typescript/classes/bearertoken/) | class | A Bedrock bearer token, the region it was minted for, and when it stops working. |
| [`BudgetVerdict`](/microvms-agentd/reference/typescript/classes/budgetverdict/) | class | A report's total judged against a budget: core's `Budget::check`, the verdict `microvm cost --max-cost` renders. |
| [`BuildHookTimeout`](/microvms-agentd/reference/typescript/classes/buildhooktimeout/) | class | A timeout for the `ready` or `validate` image-build hook: 1..=3600 seconds. |
| [`ControlPlane`](/microvms-agentd/reference/typescript/classes/controlplane/) | class | MicroVM lifecycle by ID (get, list, suspend, resume, terminate, and wait) and image administration (list, delete, versions and their status, builds). |
| [`CostReport`](/microvms-agentd/reference/typescript/classes/costreport/) | class | Per-phase attribution for one sandbox, measured or projected. |
| [`Detached`](/microvms-agentd/reference/typescript/classes/detached/) | class | What another process needs to adopt a VM handed off by `sandbox.detach()`. |
| [`Duration`](/microvms-agentd/reference/typescript/classes/duration/) | class | Seconds, plus how we know them. |
| [`EstimatedUsd`](/microvms-agentd/reference/typescript/classes/estimatedusd/) | class | Dollars derived from published rates. Not the bill. |
| [`ExecHandle`](/microvms-agentd/reference/typescript/classes/exechandle/) | class | One exec, addressed by its caller-minted id. |
| [`ExecProcess`](/microvms-agentd/reference/typescript/classes/execprocess/) | class | A long-running exec as the AI SDK's `SandboxProcess` shape. |
| [`ExecStream`](/microvms-agentd/reference/typescript/classes/execstream/) | class | A JS async iterator over an exec's output. |
| [`KeepAwake`](/microvms-agentd/reference/typescript/classes/keepawake/) | class | A running keepalive. Call `stop()` when the work is done; `done()` resolves when it ends on its own. A garbage-collected handle stops the keepalive. |
| [`LineItem`](/microvms-agentd/reference/typescript/classes/lineitem/) | class | One phase's one billing line: what was consumed, and what that costs. |
| [`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/) | class | One named VM: everything `Sandbox.adopt` needs, under a name. |
| [`NameRegistry`](/microvms-agentd/reference/typescript/classes/nameregistry/) | class | The CLI's name registry: one owner-only JSON file per name under `<stateDir>/names/`. |
| [`PortForward`](/microvms-agentd/reference/typescript/classes/portforward/) | class | A running port-forward. Call `stop()` when done; a garbage-collected handle stops the forward and cuts its open connections. |
| [`RateTable`](/microvms-agentd/reference/typescript/classes/ratetable/) | class | The pinned rate table, and everything it says about itself. |
| [`Region`](/microvms-agentd/reference/typescript/classes/region/) | class | An AWS region, by its name. |
| [`ResidencyComparison`](/microvms-agentd/reference/typescript/classes/residencycomparison/) | class | Running versus suspended for the same VM over the same wall time. |
| [`RunHookTimeout`](/microvms-agentd/reference/typescript/classes/runhooktimeout/) | class | A timeout for the `run`, `resume`, `suspend`, or `terminate` hook: 1..=60 seconds. |
| [`Sandbox`](/microvms-agentd/reference/typescript/classes/sandbox/) | class | One MicroVM's whole life. |
| [`Session`](/microvms-agentd/reference/typescript/classes/session/) | class | One running MicroVM's control API, with the proxy auth handled for you. |
| [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | class | One of the five documented size classes. |
| [`Total`](/microvms-agentd/reference/typescript/classes/total/) | class | A report's total, which is a lower bound whenever anything is unpriced. |
| [`Tunnel`](/microvms-agentd/reference/typescript/classes/tunnel/) | class | A running tunnel. Call `stop()` when done; a garbage-collected handle stops the tunnel and cuts its open connections. |
| [`TunnelIdentity`](/microvms-agentd/reference/typescript/classes/tunnelidentity/) | class | What a launcher keeps to verify its VM: the host's secret seed and the VM's public key, both base64. |
| [`Unpriced`](/microvms-agentd/reference/typescript/classes/unpriced/) | class | A quantity we can measure but cannot price, because no rate is published. |
| [`AgentEnsureOptions`](/microvms-agentd/reference/typescript/interfaces/agentensureoptions/) | interface | What `ensureImage` builds or reuses from: the daemon binary, the build role, and where the artifact goes. |
| [`AgentImageOptions`](/microvms-agentd/reference/typescript/interfaces/agentimageoptions/) | interface | What an agent image is derived from: the daemon binary and the build role. |
| [`AgentLaunchOptions`](/microvms-agentd/reference/typescript/interfaces/agentlaunchoptions/) | interface | Everything a launch takes beyond what the layer fixes (egress on, the image). |
| [`AgentSpec`](/microvms-agentd/reference/typescript/interfaces/agentspec/) | interface | A resolved spec: the model it will use and the command `prompt` runs. |
| [`AgentSpecInput`](/microvms-agentd/reference/typescript/interfaces/agentspecinput/) | interface | One agent to install: its name, and the two defaults a caller may override. |
| [`BaseImageInput`](/microvms-agentd/reference/typescript/interfaces/baseimageinput/) | interface | The platform's managed base image, paired with the Dockerfile `FROM` it goes with. |
| [`BuildImageOptions`](/microvms-agentd/reference/typescript/interfaces/buildimageoptions/) | interface | Everything `CreateMicrovmImage` needs. |
| [`CompletionRequest`](/microvms-agentd/reference/typescript/interfaces/completionrequest/) | interface | How `runToCompletion` should start and collect a command. |
| [`ConnectionEnd`](/microvms-agentd/reference/typescript/interfaces/connectionend/) | interface | A connection that didn't end clean. |
| [`DeleteImageOptions`](/microvms-agentd/reference/typescript/interfaces/deleteimageoptions/) | interface | How `deleteImage` retries while the image refuses. |
| [`DetachedObject`](/microvms-agentd/reference/typescript/interfaces/detachedobject/) | interface | `Detached` as a plain object, token included, for a private store. |
| [`Discovery`](/microvms-agentd/reference/typescript/interfaces/discovery/) | interface | Image configuration. A missing discovery response means an older daemon. |
| [`DownloadedFile`](/microvms-agentd/reference/typescript/interfaces/downloadedfile/) | interface | One file `downloadDir` wrote. |
| [`DownloadFileOptions`](/microvms-agentd/reference/typescript/interfaces/downloadfileoptions/) | interface | The line range `downloadFile` reads, 1-based and inclusive. Both absent reads the file. |
| [`EnsuredImage`](/microvms-agentd/reference/typescript/interfaces/ensuredimage/) | interface | What `ensureImage` returns: the ready image and how this call got it. |
| [`EnsureImageOptions`](/microvms-agentd/reference/typescript/interfaces/ensureimageoptions/) | interface | Everything `ensureImage` needs besides the size class. |
| [`ExecOptions`](/microvms-agentd/reference/typescript/interfaces/execoptions/) | interface | How an exec should be started. Every field optional; the defaults are the daemon's. |
| [`ExecResult`](/microvms-agentd/reference/typescript/interfaces/execresult/) | interface | An exec's phase and, once it has one, its outcome. |
| [`HandlerOutcome`](/microvms-agentd/reference/typescript/interfaces/handleroutcome/) | interface | What a workload's hook handler did. Its output is in the daemon's log, not here. |
| [`Health`](/microvms-agentd/reference/typescript/interfaces/health/) | interface | The daemon's liveness answer. `bootstrapped` is the useful field. |
| [`HookObservation`](/microvms-agentd/reference/typescript/interfaces/hookobservation/) | interface | One lifecycle-hook invocation, as the daemon observed it. |
| [`IdentityStep`](/microvms-agentd/reference/typescript/interfaces/identitystep/) | interface | One identity-repair step. |
| [`IdlePolicy`](/microvms-agentd/reference/typescript/interfaces/idlepolicy/) | interface | The idle policy the service reports a VM is running under. |
| [`Image`](/microvms-agentd/reference/typescript/interfaces/image/) | interface | A built image, and the log group the service created alongside it. |
| [`ImageBuild`](/microvms-agentd/reference/typescript/interfaces/imagebuild/) | interface | One build of an image version: one per Graviton generation, so a version's builds differ in `chipsetGeneration`. `getImageBuild` adds the snapshot sizes the listing lacks. |
| [`ImageSummary`](/microvms-agentd/reference/typescript/interfaces/imagesummary/) | interface | One `ListMicrovmImages` item: an image's ARN, name and state. |
| [`ImageVersion`](/microvms-agentd/reference/typescript/interfaces/imageversion/) | interface | One image version as `ListMicrovmImageVersions` or `UpdateMicrovmImageVersion` reads it back: its build state, whether `RunMicrovm` launches it, and what it was built with. |
| [`KeepAwakeOptions`](/microvms-agentd/reference/typescript/interfaces/keepawakeoptions/) | interface | The options bag for `keepAwake`. |
| [`KeepAwakeReport`](/microvms-agentd/reference/typescript/interfaces/keepawakereport/) | interface | What a finished keepalive did. |
| [`LaunchMetrics`](/microvms-agentd/reference/typescript/interfaces/launchmetrics/) | interface | Observations made by the client during launch. |
| [`ListMicrovmsOptions`](/microvms-agentd/reference/typescript/interfaces/listmicrovmsoptions/) | interface | The service's optional `ListMicrovms` filters. |
| [`ManagedBaseVersion`](/microvms-agentd/reference/typescript/interfaces/managedbaseversion/) | interface | The three guarded values a build takes, as separate parameters rather than fields. |
| [`Microvm`](/microvms-agentd/reference/typescript/interfaces/microvm/) | interface | A MicroVM as `GetMicrovm` last described it. |
| [`MicrovmSummary`](/microvms-agentd/reference/typescript/interfaces/microvmsummary/) | interface | One `ListMicrovms` item: narrower than `Microvm`, with no endpoint or reason. |
| [`NameRecordObject`](/microvms-agentd/reference/typescript/interfaces/namerecordobject/) | interface | A record's JSON-safe form, with the CLI registry's camelCase keys. **Holds the agent token**; store it privately. |
| [`OutputGap`](/microvms-agentd/reference/typescript/interfaces/outputgap/) | interface | One byte range the daemon could not replay. |
| [`PlanUsageOptions`](/microvms-agentd/reference/typescript/interfaces/planusageoptions/) | interface | A plan's phases, in plain seconds, before anything is spent. |
| [`PortForwardReport`](/microvms-agentd/reference/typescript/interfaces/portforwardreport/) | interface | What a stopped port-forward did. |
| [`PreflightCheck`](/microvms-agentd/reference/typescript/interfaces/preflightcheck/) | interface | One line of a preflight report. |
| [`PreflightReport`](/microvms-agentd/reference/typescript/interfaces/preflightreport/) | interface | What `preflight` found: three checks and whether a launch could proceed. |
| [`ProcessExit`](/microvms-agentd/reference/typescript/interfaces/processexit/) | interface | What `wait()` resolves to. |
| [`ProcGroup`](/microvms-agentd/reference/typescript/interfaces/procgroup/) | interface | One exec's process group, as `GET /v1/procs` reports it. |
| [`PromptOptions`](/microvms-agentd/reference/typescript/interfaces/promptoptions/) | interface | The knobs on one prompt. |
| [`ProvisionedAgentd`](/microvms-agentd/reference/typescript/interfaces/provisionedagentd/) | interface | A provisioned `agentd` binary and how it got here: `provisionAgentdReport()`'s answer. |
| [`ProvisionOptions`](/microvms-agentd/reference/typescript/interfaces/provisionoptions/) | interface | What to provision. Every field is optional. |
| [`RetryDetails`](/microvms-agentd/reference/typescript/interfaces/retrydetails/) | interface | Retry telemetry on a control-plane failure. Attempts include the first request. |
| [`RetryOptions`](/microvms-agentd/reference/typescript/interfaces/retryoptions/) | interface | Optional throttle-only budget; attempts include the first request. |
| [`RunOptions`](/microvms-agentd/reference/typescript/interfaces/runoptions/) | interface | Everything a launch needs. |
| [`RunUsageOptions`](/microvms-agentd/reference/typescript/interfaces/runusageoptions/) | interface | Everything a measured report attributes cost to. |
| [`ServeOptions`](/microvms-agentd/reference/typescript/interfaces/serveoptions/) | interface | Where a tunnel or a port-forward listens, and when it stops on its own. |
| [`SpawnOptions`](/microvms-agentd/reference/typescript/interfaces/spawnoptions/) | interface | How a `spawn` should behave: the exec's own options, plus the stream's. |
| [`StdinAck`](/microvms-agentd/reference/typescript/interfaces/stdinack/) | interface | What a stdin write accomplished. |
| [`StreamEvent`](/microvms-agentd/reference/typescript/interfaces/streamevent/) | interface | One event off an exec's output stream. |
| [`StreamOptionsInput`](/microvms-agentd/reference/typescript/interfaces/streamoptionsinput/) | interface | How a stream should behave. |
| [`SweepFailure`](/microvms-agentd/reference/typescript/interfaces/sweepfailure/) | interface | - |
| [`SweepOptions`](/microvms-agentd/reference/typescript/interfaces/sweepoptions/) | interface | Prefix cleanup options. Omitted options preserve the dry-run default. |
| [`SweepReport`](/microvms-agentd/reference/typescript/interfaces/sweepreport/) | interface | Inventory and confirmed outcomes of prefix cleanup. |
| [`SyncDirOptions`](/microvms-agentd/reference/typescript/interfaces/syncdiroptions/) | interface | How `syncDir` should behave. |
| [`SyncReport`](/microvms-agentd/reference/typescript/interfaces/syncreport/) | interface | What one `syncDir` did. |
| [`TeardownOptions`](/microvms-agentd/reference/typescript/interfaces/teardownoptions/) | interface | What a teardown should delete beyond the VM itself. |
| [`TeardownReport`](/microvms-agentd/reference/typescript/interfaces/teardownreport/) | interface | What a teardown did, and what it left behind. |
| [`TunnelReport`](/microvms-agentd/reference/typescript/interfaces/tunnelreport/) | interface | What a stopped tunnel did. |
| [`WaitForStateOptions`](/microvms-agentd/reference/typescript/interfaces/waitforstateoptions/) | interface | How `waitForState` polls. |
| [`WrapDockerfileOptions`](/microvms-agentd/reference/typescript/interfaces/wrapdockerfileoptions/) | interface | What `wrapDockerfile` takes besides the task text. Every field is optional. |
| [`agentConstants`](/microvms-agentd/reference/typescript/module/#agentconstants) | function | The layer's fixed values as JSON, for a caller that wants to reason about the guest. |
| [`baseImageFromDockerfile`](/microvms-agentd/reference/typescript/module/#baseimagefromdockerfile) | function | 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. |
| [`buildUnpricedReason`](/microvms-agentd/reference/typescript/module/#buildunpricedreason) | function | Why the image build has no price, as the reason that lands on the line item. |
| [`checkBudget`](/microvms-agentd/reference/typescript/module/#checkbudget) | function | 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. |
| [`compareResidency`](/microvms-agentd/reference/typescript/module/#compareresidency) | function | The warm-pool argument, with its own counter-argument attached. |
| [`coreVersion`](/microvms-agentd/reference/typescript/module/#coreversion) | function | The core crate's version, for a `doctor` or `manifest` command to report. |
| [`costConstants`](/microvms-agentd/reference/typescript/module/#costconstants) | function | The documented cost constants, as a JSON string a caller can assert against. |
| [`defaultBaseImage`](/microvms-agentd/reference/typescript/module/#defaultbaseimage) | function | The managed Amazon Linux 2023 base used for measurements in `docs/PLATFORM.md`. |
| [`egressPostureFor`](/microvms-agentd/reference/typescript/module/#egressposturefor) | function | The egress posture `sandbox.run` with these options would report, without launching. |
| [`errorCodes`](/microvms-agentd/reference/typescript/module/#errorcodes) | function | Every `ERR_*` code this library can raise, for a caller building an exhaustive switch. |
| [`estimateRun`](/microvms-agentd/reference/typescript/module/#estimaterun) | function | What a plan will cost, before spending anything (COST-10). |
| [`installAgentAccess`](/microvms-agentd/reference/typescript/module/#installagentaccess) | function | Installs Bedrock access for `agents` into a running VM over `session`. |
| [`installedAgents`](/microvms-agentd/reference/typescript/module/#installedagents) | function | The agents a running VM was provisioned with, read from its guest marker. |
| [`isRetryable`](/microvms-agentd/reference/typescript/module/#isretryable) | function | Whether retrying the identical call could plausibly succeed, for an error this library raised. |
| [`mintBedrockToken`](/microvms-agentd/reference/typescript/module/#mintbedrocktoken) | function | Mints a Bedrock bearer token from the default credential chain. |
| [`mintBedrockTokenWithCredentials`](/microvms-agentd/reference/typescript/module/#mintbedrocktokenwithcredentials) | function | Mint using explicit STS credentials without changing the process environment. credentialsExpiresAt is Unix seconds from STS Expiration. Do not log these inputs. |
| [`preflight`](/microvms-agentd/reference/typescript/module/#preflight) | function | Whether a harness can launch in `region` (default: `$AWS_REGION`, `$AWS_DEFAULT_REGION`, then us-east-1), checked before it queues work. |
| [`promptAgent`](/microvms-agentd/reference/typescript/module/#promptagent) | function | Starts one task for `agent` over `session` and resolves with its handle. Does not wait. |
| [`provisionAgentd`](/microvms-agentd/reference/typescript/module/#provisionagentd) | function | The `agentd` daemon binary for `options.version` (default: this client's own). |
| [`provisionAgentdReport`](/microvms-agentd/reference/typescript/module/#provisionagentdreport) | function | `provisionAgentd`, answering with the bytes and how they got here. |
| [`retryDetails`](/microvms-agentd/reference/typescript/module/#retrydetails) | function | Reads typed telemetry from a control-plane rejection, or returns null for other errors. |
| [`runReport`](/microvms-agentd/reference/typescript/module/#runreport) | function | Per-phase attribution for one sandbox's lifecycle. |
| [`sessionConstants`](/microvms-agentd/reference/typescript/module/#sessionconstants) | function | The daemon's protocol constants, as a JSON string, for a caller asserting against the wire contract. |
| [`wireKinds`](/microvms-agentd/reference/typescript/module/#wirekinds) | function | Every daemon-status class, as `err.cause.cause.message` names them. |
| [`wrapDockerfile`](/microvms-agentd/reference/typescript/module/#wrapdockerfile) | function | A task Dockerfile with the agentd stanza appended, ready for `buildImage`. |
| [`wrapDockerfilePreservingUser`](/microvms-agentd/reference/typescript/module/#wrapdockerfilepreservinguser) | function | 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`. |
| [`__napiBindingTarget`](/microvms-agentd/reference/typescript/module/#__napibindingtarget) | constant | 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. |
| [`GapPolicy`](/microvms-agentd/reference/typescript/module/#gappolicy) | enum | What to do when the daemon reports evicted output. |

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