microvms: functions, constants, and enums

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

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

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

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

function agentConstants(): string;

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

Returns

string

---

baseImageFromDockerfile()

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

---

buildUnpricedReason()

function buildUnpricedReason(): string;

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

Returns

string

---

checkBudget()

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
maxUsd	string
onBreach	string

Returns

BudgetVerdict

---

compareResidency()

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
holdSeconds	number
cycles?	number | null
rates?	RateTable | null

Returns

ResidencyComparison

---

coreVersion()

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

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

function defaultBaseImage(): BaseImageInput;

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

Returns

BaseImageInput

---

egressPostureFor()

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

Returns

string

---

errorCodes()

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

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
options?	PlanUsageOptions | null
rates?	RateTable | null

Returns

CostReport

---

installAgentAccess()

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
agents	AgentSpecInput[]
token	BearerToken

Returns

Promise<void>

---

installedAgents()

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

Returns

Promise<AgentSpec[]>

---

isRetryable()

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

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

Returns

Promise<BearerToken>

---

mintBedrockTokenWithCredentials()

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
accessKeyId	string
secretAccessKey	string
sessionToken	string | null | undefined
credentialsExpiresAt	number
ttlSeconds?	number | null

Returns

BearerToken

---

preflight()

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

Returns

Promise<PreflightReport>

---

promptAgent()

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
agent	AgentSpecInput
task	string
options?	PromptOptions | null

Returns

Promise<ExecHandle>

---

provisionAgentd()

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

Returns

Promise<Buffer<ArrayBufferLike>>

---

provisionAgentdReport()

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

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

Parameters

Parameter	Type
options?	ProvisionOptions | null

Returns

Promise<ProvisionedAgentd>

---

retryDetails()

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

---

runReport()

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
options?	RunUsageOptions | null
rates?	RateTable | null

Returns

CostReport

---

sessionConstants()

function sessionConstants(): string;

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

Returns

string

---

wireKinds()

function wireKinds(): string[];

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

Returns

string[]

---

wrapDockerfile()

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

Returns

string

---

wrapDockerfilePreservingUser()

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