Sandbox

View as Markdown Open in ChatGPT Open in Claude Open in Claude Code Open in Cursor

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

1
adopted(): Promise<boolean>;

Whether this sandbox was built by adopt rather than by its own launch.

Returns

Promise<boolean>

bootstrapCount()

1
bootstrapCount(): Promise<number>;

How many times the token has been installed. Never above one (STATE-3).

Returns

Promise<number>

buildArtifact()

1
buildArtifact(
2
   options: BuildImageOptions,
3
   size?: SizeClass | null,
4
   runHookTimeout?: RunHookTimeout | null,
5
   buildHookTimeout?: BuildHookTimeout | null
6
): Promise<Buffer<ArrayBufferLike>>;

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`
`size?`	`SizeClass` \| `null`
`runHookTimeout?`	`RunHookTimeout` \| `null`
`buildHookTimeout?`	`BuildHookTimeout` \| `null`

Returns

Promise<Buffer<ArrayBufferLike>>

buildImage()

1
buildImage(
2
   options: BuildImageOptions,
3
   size?: SizeClass | null,
4
   runHookTimeout?: RunHookTimeout | null,
5
   buildHookTimeout?: BuildHookTimeout | null
6
): Promise<Image>;

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`
`size?`	`SizeClass` \| `null`
`runHookTimeout?`	`RunHookTimeout` \| `null`
`buildHookTimeout?`	`BuildHookTimeout` \| `null`

Returns

Promise<Image>

detach()

1
detach(): Promise<Detached>;

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>

endpoint()

1
endpoint(): Promise<string | null>;

The proxy endpoint, once launched.

Returns

Promise<string | null>

ensureImage()

1
ensureImage(options: EnsureImageOptions, size?: SizeClass | null): Promise<EnsuredImage>;

Builds or reuses the content-addressed image for a task: one call from build inputs to a ready image.

The name is <namePrefix>-<hash12> 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://<s3Bucket>/<s3KeyPrefix>/<name>/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`
`size?`	`SizeClass` \| `null`

Returns

Promise<EnsuredImage>

image()

1
image(): Promise<Image | null>;

The image, once built.

Returns

Promise<Image | null>

imageExists()

1
imageExists(): Promise<boolean>;

Whether an image is recorded as existing (STATE-1).

Returns

Promise<boolean>

isDetached()

1
isDetached(): Promise<boolean>;

Whether detach() handed this sandbox’s VM to another process.

Returns

Promise<boolean>

launchImageArn()

1
launchImageArn(): Promise<string | null>;

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

1
lifecycle(): Promise<string>;

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

1
managedBaseVersions(baseImageArn: string): Promise<ManagedBaseVersion[]>;

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[]>

microvmId()

1
microvmId(): Promise<string | null>;

The VM id, once launched.

Returns

Promise<string | null>

preflight()

1
preflight(
2
   options: BuildImageOptions,
3
   size?: SizeClass | null,
4
   runHookTimeout?: RunHookTimeout | null,
5
   buildHookTimeout?: BuildHookTimeout | null
6
): Promise<void>;

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`
`size?`	`SizeClass` \| `null`
`runHookTimeout?`	`RunHookTimeout` \| `null`
`buildHookTimeout?`	`BuildHookTimeout` \| `null`

Returns

Promise<void>

resume()

1
resume(): Promise<Session>;

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>

run()

1
run(options?: RunOptions | null): Promise<Session>;

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

Returns

Promise<Session>

session()

1
session(): Promise<Session | null>;

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

stateReason()

1
stateReason(): Promise<string | null>;

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

1
suspend(): Promise<string>;

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

1
suspendedWindowSecondsAsync(): Promise<number | null>;

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

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

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

Returns

Promise<TeardownReport>

tokenInstalled()

1
tokenInstalled(): Promise<boolean>;

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

1
tunnelIdentity(): Promise<TunnelIdentity | null>;

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

waitUntilRunning()

1
waitUntilRunning(timeout?: number | null): Promise<Session>;

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>

wasTerminated()

1
wasTerminated(): Promise<boolean>;

Whether this VM was ever terminated (STATE-11).

Returns

Promise<boolean>

adopt()

1
static adopt(
2
   region: Region,
3
   microvmId: string,
4
   endpoint: string,
5
   agentToken: string,
6
   port?: number | null
7
): Promise<Sandbox>;

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`
`microvmId`	`string`
`endpoint`	`string`
`agentToken`	`string`
`port?`	`number` \| `null`

Returns

Promise<Sandbox>

create()

1
static create(region: Region, retry?: RetryOptions | null): Promise<Sandbox>;

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`
`retry?`	`RetryOptions` \| `null`

Returns

Promise<Sandbox>

fromName()

1
static fromName(
2
   region: Region,
3
   name: string,
4
   registry: NameRegistry,
5
   port?: number | null
6
): Promise<Sandbox>;

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`
`name`	`string`
`registry`	`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.