--- title: Sandbox description: "One MicroVM's whole life." --- One MicroVM's whole life. The five transitions are `buildImage`, `run`, `suspend`, `resume`, and `terminate`, and every state guard lives in the core — see the module docs. ## Methods ### adopted() ```ts adopted(): Promise; ``` Whether this sandbox was built by `adopt` rather than by its own launch. #### Returns `Promise`\<`boolean`> *** ### bootstrapCount() ```ts bootstrapCount(): Promise; ``` How many times the token has been installed. Never above one (STATE-3). #### Returns `Promise`\<`number`> *** ### buildArtifact() ```ts buildArtifact( options: BuildImageOptions, size?: SizeClass | null, runHookTimeout?: RunHookTimeout | null, buildHookTimeout?: BuildHookTimeout | null ): Promise>; ``` The artifact bytes to upload to `codeArtifactUri`. The upload is the caller's on this path (`ensureImage` uploads for itself). Takes the same options as \[`Self::build_image`] so the bytes a caller puts in the bucket are the bytes the build will receive. #### Parameters | Parameter | Type | | ------ | ------ | | `options` | [`BuildImageOptions`](/microvms-agentd/reference/typescript/interfaces/buildimageoptions/) | | `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` | | `runHookTimeout?` | [`RunHookTimeout`](/microvms-agentd/reference/typescript/classes/runhooktimeout/) | `null` | | `buildHookTimeout?` | [`BuildHookTimeout`](/microvms-agentd/reference/typescript/classes/buildhooktimeout/) | `null` | #### Returns `Promise`\<`Buffer`\<`ArrayBufferLike`>> *** ### buildImage() ```ts buildImage( options: BuildImageOptions, size?: SizeClass | null, runHookTimeout?: RunHookTimeout | null, buildHookTimeout?: BuildHookTimeout | null ): Promise; ``` Builds an image and waits for it to become usable. Every local guard runs **before** the call, which matters because the create happens after the caller's artifact upload: a rejection AWS raises costs the upload first. #### Parameters | Parameter | Type | | ------ | ------ | | `options` | [`BuildImageOptions`](/microvms-agentd/reference/typescript/interfaces/buildimageoptions/) | | `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` | | `runHookTimeout?` | [`RunHookTimeout`](/microvms-agentd/reference/typescript/classes/runhooktimeout/) | `null` | | `buildHookTimeout?` | [`BuildHookTimeout`](/microvms-agentd/reference/typescript/classes/buildhooktimeout/) | `null` | #### Returns `Promise`\<[`Image`](/microvms-agentd/reference/typescript/interfaces/image/)> *** ### detach() ```ts detach(): Promise; ``` Hands the VM off to another process and resolves with what that process adopts it with. For a workflow whose steps run in different processes: the launching step calls this instead of dropping the sandbox (which warns that a live VM was abandoned), persists the record privately, and a later step calls `Sandbox.adopt` with it. The VM keeps running and no AWS call is made. Afterwards this sandbox is inert: `run`, `waitUntilRunning`, `suspend`, `resume`, and `terminate` are refused. Rejects with `ERR_PRECONDITION` without a live VM or when already detached. #### Returns `Promise`\<[`Detached`](/microvms-agentd/reference/typescript/classes/detached/)> *** ### endpoint() ```ts endpoint(): Promise; ``` The proxy endpoint, once launched. #### Returns `Promise`\<`string` | `null`> *** ### ensureImage() ```ts ensureImage(options: EnsureImageOptions, size?: SizeClass | null): Promise; ``` Builds or reuses the content-addressed image for a task: one call from build inputs to a ready image. The name is `-` over the daemon, the Dockerfile, the build context, the base image and the size class. A ready image is returned with `reused: true` and no upload; a running build is waited out; a failed image — or any image under `force` — is deleted and rebuilt; an absent one is uploaded to `s3://///artifact.zip`, created, and waited for. When a concurrent caller creates the name first, this call waits for that build and returns it with `reused: true`. Every local check runs before the first AWS call. #### Parameters | Parameter | Type | | ------ | ------ | | `options` | [`EnsureImageOptions`](/microvms-agentd/reference/typescript/interfaces/ensureimageoptions/) | | `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` | #### Returns `Promise`\<[`EnsuredImage`](/microvms-agentd/reference/typescript/interfaces/ensuredimage/)> *** ### image() ```ts image(): Promise; ``` The image, once built. #### Returns `Promise`\<[`Image`](/microvms-agentd/reference/typescript/interfaces/image/) | `null`> *** ### imageExists() ```ts imageExists(): Promise; ``` Whether an image is recorded as existing (STATE-1). #### Returns `Promise`\<`boolean`> *** ### isDetached() ```ts isDetached(): Promise; ``` Whether `detach()` handed this sandbox's VM to another process. #### Returns `Promise`\<`boolean`> *** ### launchImageArn() ```ts launchImageArn(): Promise; ``` The image ARN `run` sent in `RunMicrovm`: the caller's identifier with a bare name resolved, or the built image's. Recorded before the call, so a launch the service refused still names the image it asked for. `null` until `run` has resolved an image, and on an adopted sandbox. #### Returns `Promise`\<`string` | `null`> *** ### lifecycle() ```ts lifecycle(): Promise; ``` The lifecycle state: `"PENDING"`, `"RUNNING"`, `"SUSPENDING"`, `"SUSPENDED"`, `"TERMINATING"`, or `"TERMINATED"`. Spelled as the service spells it, because a reader compares it against a `GetMicrovm` response and `Suspended` beside `SUSPENDED` reads like two facts. #### Returns `Promise`\<`string`> *** ### managedBaseVersions() ```ts managedBaseVersions(baseImageArn: string): Promise; ``` `ListManagedMicrovmImageVersions`, every page: the versions of a managed base, the values `buildImage`'s base-version pin takes. `baseImageArn` is the base's full ARN, such as `arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1`; a bare name is refused. #### Parameters | Parameter | Type | | ------ | ------ | | `baseImageArn` | `string` | #### Returns `Promise`\<[`ManagedBaseVersion`](/microvms-agentd/reference/typescript/interfaces/managedbaseversion/)\[]> *** ### microvmId() ```ts microvmId(): Promise; ``` The VM id, once launched. #### Returns `Promise`\<`string` | `null`> *** ### preflight() ```ts preflight( options: BuildImageOptions, size?: SizeClass | null, runHookTimeout?: RunHookTimeout | null, buildHookTimeout?: BuildHookTimeout | null ): Promise; ``` Every local guard `buildImage` runs, with zero calls: rejects with the refusal `buildImage` would, so a caller who uploads its own artifact checks the request before paying for the upload. Takes `buildImage`'s arguments. #### Parameters | Parameter | Type | | ------ | ------ | | `options` | [`BuildImageOptions`](/microvms-agentd/reference/typescript/interfaces/buildimageoptions/) | | `size?` | [`SizeClass`](/microvms-agentd/reference/typescript/classes/sizeclass/) | `null` | | `runHookTimeout?` | [`RunHookTimeout`](/microvms-agentd/reference/typescript/classes/runhooktimeout/) | `null` | | `buildHookTimeout?` | [`BuildHookTimeout`](/microvms-agentd/reference/typescript/classes/buildhooktimeout/) | `null` | #### Returns `Promise`\<`void`> *** ### resume() ```ts resume(): Promise; ``` Thaws the VM and resolves with a usable session. **What the core refuses, before any wire call** A resume after `terminate` (STATE-11) — a terminated VM never returns to RUNNING, and even a call the service accepted would hand back a different machine. A handle in neither RUNNING nor SUSPENDED also refuses locally (STATE-7). **What the service decides (STATE-12)** How long the VM has been suspended. The `idlePolicy` terminates a VM the idle policy suspended once `suspendedSec` passes, and a VM this sandbox suspended stayed resumable 1283 s into a 60 s window (measured 2026-10-12, us-east-1). `ERR_WINDOW_CLOSED` reports a VM the service says is TERMINATING or TERMINATED, whatever ended it. The sandbox records it as TERMINATED. With a locally RUNNING handle, `resume` reads `GetMicrovm` first. It resumes an observed SUSPENDED VM and reports `ERR_WINDOW_CLOSED` for a VM that has ended. Other known service states refuse the request; a later call can read the service again. Nothing is re-delivered: no run-hook payload, no token, no bootstrap. The in-memory token survived the freeze, and re-delivering it would hit the daemon's one-shot bootstrap and be refused — a 409 that reads like a broken VM. #### Returns `Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/)> *** ### run() ```ts run(options?: RunOptions | null): Promise; ``` Launches a MicroVM and resolves with its session. By default it waits for RUNNING and for the daemon to answer; `wait: false` skips those readiness waits. `readyTimeout` bounds the wait for RUNNING; the wait for the daemon after it is `sessionConstants().defaultReadyTimeoutSeconds`, and a daemon that never answers rejects with `ERR_TIMEOUT` with the VM left RUNNING. **What the core refuses here, and this file does not** A second `run` on one sandbox, with **zero** control-plane calls: the agent token is installed at most once per VM lifetime (STATE-3), and a second VM needs a second `Sandbox`. A run with no image at all, before any call. Neither check is in this file. #### Parameters | Parameter | Type | | ------ | ------ | | `options?` | [`RunOptions`](/microvms-agentd/reference/typescript/interfaces/runoptions/) | `null` | #### Returns `Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/)> *** ### session() ```ts session(): Promise; ``` The session, once launched. A new wrapper each call, all reaching the same session under the same lock. There is no cached instance: caching one would mean a session object that outlives the VM it addresses, and the indirection exists precisely so a post-terminate call reports the lifecycle rather than a dangling handle. #### Returns `Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/) | `null`> *** ### stateReason() ```ts stateReason(): Promise; ``` Why the VM is in its current state, when the service said. The absence is information: TRAP-8's message distinguishes "no stateReason" from an empty one. #### Returns `Promise`\<`string` | `null`> *** ### suspend() ```ts suspend(): Promise; ``` Freezes the VM and waits for the platform to report it. A freeze and restore rather than a stop and start: the guest keeps its memory, so the token, the filesystem, and every exec record survive. The one thing that does not is the guest's view of time — it observes the whole suspension as a single jump, so any timeout, lease, or TLS session a running command holds expires at once on resume. A suspend from anything but RUNNING is refused by the core with zero control-plane calls (STATE-5). Resolves with the state reached, which may be `"TERMINATED"`: a VM that dies while suspending is a state to report rather than an error thrown out of the middle of a teardown. #### Returns `Promise`\<`string`> *** ### suspendedWindowSecondsAsync() ```ts suspendedWindowSecondsAsync(): Promise; ``` The suspended window this sandbox asked for at launch, in seconds. `null` before this sandbox launches a VM. This accessor reports the requested window; `GetMicrovm` also returns the service's idle policy. #### Returns `Promise`\<`number` | `null`> *** ### terminate() ```ts terminate(options?: TeardownOptions | null): Promise; ``` Tears down, best-effort, **never rejecting**. Order: VM, then image, then the log group last, because the service can recreate a group deleted before its image. #### Parameters | Parameter | Type | | ------ | ------ | | `options?` | [`TeardownOptions`](/microvms-agentd/reference/typescript/interfaces/teardownoptions/) | `null` | #### Returns `Promise`\<[`TeardownReport`](/microvms-agentd/reference/typescript/interfaces/teardownreport/)> *** ### tokenInstalled() ```ts tokenInstalled(): Promise; ``` Whether the agent token has been installed (STATE-2). Set by the platform reporting RUNNING, not by the launch call: the run hook is what delivers the token, and a launch that died during startup delivered nothing. #### Returns `Promise`\<`boolean`> *** ### tunnelIdentity() ```ts tunnelIdentity(): Promise; ``` The tunnel identity a launch with `identity: true` generated, or that an adopted record carried; `null` otherwise. Holds the host's secret half: pass it to `session.tunnel(...)`, and store it only where the agent token goes. #### Returns `Promise`\<[`TunnelIdentity`](/microvms-agentd/reference/typescript/classes/tunnelidentity/) | `null`> *** ### waitUntilRunning() ```ts waitUntilRunning(timeout?: number | null): Promise; ``` Finishes a `run({ wait: false })`: waits for RUNNING and for the daemon to answer, and resolves with the session. `timeout` bounds the wait for RUNNING, as `readyTimeout` does. A launch whose `clientToken` adopted an existing, idle-suspended VM resumes it; a fresh launch that reaches a terminal state first rejects with the service's `stateReason`. Refused unless the launch is still PENDING. #### Parameters | Parameter | Type | | ------ | ------ | | `timeout?` | `number` | `null` | #### Returns `Promise`\<[`Session`](/microvms-agentd/reference/typescript/classes/session/)> *** ### wasTerminated() ```ts wasTerminated(): Promise; ``` Whether this VM was ever terminated (STATE-11). #### Returns `Promise`\<`boolean`> *** ### adopt() ```ts static adopt( region: Region, microvmId: string, endpoint: string, agentToken: string, port?: number | null ): Promise; ``` A sandbox for a VM another process launched, from its private record. The lifecycle is read from `GetMicrovm`, so suspend, resume, and terminate start from the service's state and keep every guard. The VM was bootstrapped by its own launch, so `run` is refused and no run-hook payload is ever sent. Never publish or log `agentToken`; it appears in no error. #### Parameters | Parameter | Type | | ------ | ------ | | `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) | | `microvmId` | `string` | | `endpoint` | `string` | | `agentToken` | `string` | | `port?` | `number` | `null` | #### Returns `Promise`\<`Sandbox`> *** ### create() ```ts static create(region: Region, retry?: RetryOptions | null): Promise; ``` Resolves credentials for `region` and returns a sandbox with nothing launched. A factory rather than a constructor because credential resolution is async, and a `#[napi(constructor)]` cannot be. `region` is a \[`Region`] instance and not a string, so a malformed region name never reaches this call. #### Parameters | Parameter | Type | | ------ | ------ | | `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) | | `retry?` | [`RetryOptions`](/microvms-agentd/reference/typescript/interfaces/retryoptions/) | `null` | #### Returns `Promise`\<`Sandbox`> *** ### fromName() ```ts static fromName( region: Region, name: string, registry: NameRegistry, port?: number | null ): Promise; ``` Adopts the VM registered as `name` in `registry`; see `Sandbox.adopt`. `region` must match the record's: an id from another region addresses nothing here. #### Parameters | Parameter | Type | | ------ | ------ | | `region` | [`Region`](/microvms-agentd/reference/typescript/classes/region/) | | `name` | `string` | | `registry` | [`NameRegistry`](/microvms-agentd/reference/typescript/classes/nameregistry/) | | `port?` | `number` | `null` | #### Returns `Promise`\<`Sandbox`> ## 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.