---
title: RunOptions
description: Everything a launch needs.
---

Everything a launch needs.

## Properties

### agentToken?

```ts
optional agentToken?: string;
```

The bearer token the daemon will accept, or omitted to mint one.

Optional because the common case is a per-VM secret nobody needs to see; a caller who
has one already — a harness minting its own, or a retry that must reuse the first
attempt's — passes it. It rides in `runHookPayload`, which is what keeps it out of the
shared image snapshot.

***

### autoResume?

```ts
optional autoResume?: boolean;
```

***

### clientToken?

```ts
optional clientToken?: string;
```

Persist once per intended launch and reuse with the identical request.

***

### denyEgress?

```ts
optional denyEgress?: boolean;
```

Set advisory HTTP proxy variables. Workloads can ignore or override them;
use a VPC without an internet gateway or NAT gateway for no egress.

***

### disableLogging?

```ts
optional disableLogging?: boolean;
```

Turns per-VM logging off. Cannot be combined with `logGroup` or `logStream`.

***

### egress?

```ts
optional egress?: boolean;
```

Request the managed INTERNET\_EGRESS connector. Omission does not block egress.

***

### egressNetworkConnectors?

```ts
optional egressNetworkConnectors?: string[];
```

Existing VPC network connector ARNs. For no egress, use a VPC without an
internet gateway or NAT gateway. Cannot be combined with `egress: true`.

***

### executionRoleArn?

```ts
optional executionRoleArn?: string;
```

The execution role. Optional in the model; every real launch needs one.

***

### identity?

```ts
optional identity?: boolean;
```

Generate a tunnel identity and deliver the VM's half with the launch, so
`session.tunnel(port, {}, await sandbox.tunnelIdentity())` can prove the far end is
this VM's daemon.

***

### imageIdentifier?

```ts
optional imageIdentifier?: string;
```

The image to launch, as an ARN or a bare image name, or omitted for the one
`buildImage` built. The core resolves a name to its ARN with one `ListMicrovmImages`
read, and a name no image carries is refused with `ERR_PRECONDITION` before anything
launches.

***

### imageVersion?

```ts
optional imageVersion?: string;
```

`imageVersion`, or omitted for the image's own latest active version.

Pinning is what makes a canary launch against the version it means to test rather than
against whatever became latest while it was starting, and it is the half of a rollback
that re-points at the known-good build. A version the control plane has set INACTIVE
refuses to launch when named here.

***

### launchEnv?

```ts
optional launchEnv?: Record<string, string>;
```

Base environment for every exec in the launched VM, delivered in the same
`runHookPayload` as the token.

Applied *under* each exec's own `env`, so a per-exec value wins on a shared key.
Shares the token's 4096-byte payload budget; the core refuses an over-ceiling
payload before the launch, naming the byte count.

***

### logGroup?

```ts
optional logGroup?: string;
```

Per-VM CloudWatch log group. Omitted keeps the service's default destination.

***

### logStream?

```ts
optional logStream?: string;
```

An exact log stream inside `logGroup`.

***

### maxDurationSec?

```ts
optional maxDurationSec?: number;
```

***

### maxIdleSec?

```ts
optional maxIdleSec?: number;
```

***

### readyTimeout?

```ts
optional readyTimeout?: number;
```

How long to wait for RUNNING. The wait for the daemon after it is the core's
`defaultReadyTimeoutSeconds`.

***

### shell?

```ts
optional shell?: boolean;
```

Whether to launch shell-capable: the ingress set becomes the measured pair
`[HTTP_INGRESS, SHELL_INGRESS]`, which is what `microvm shell` attaches to.

***

### suspendedSec?

```ts
optional suspendedSec?: number;
```

Requested suspended window, in seconds; the service also reports its idle policy.

***

### tokenScope?

```ts
optional tokenScope?: string;
```

A label for the run token. Never the token.

***

### wait?

```ts
optional wait?: boolean;
```

Whether `run` waits for RUNNING and for the daemon to answer (default `true`).
`false` resolves once the launch is accepted, with the lifecycle PENDING;
`waitUntilRunning` finishes both waits.

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