Struct RunRequest 

pub struct RunRequest {

    pub image_identifier: Option<String>,
    pub image_version: Option<String>,
    pub execution_role_arn: Option<String>,
    pub agent_token: Option<String>,
    pub client_token: Option<String>,
    pub launch_env: HashMap<String, String>,
    pub identity: bool,
    pub egress: bool,
    pub egress_network_connectors: Vec<String>,
    pub deny_egress: bool,
    pub shell: bool,
    pub max_idle_sec: u32,
    pub suspended_sec: u32,
    pub auto_resume: bool,
    pub max_duration_sec: u32,
    pub ready_timeout: Duration,
    pub token_scope: Option<String>,
    pub logging: Option<Logging>,
    pub wait: bool,
}

Everything a launch needs, with the defaults the Python client measured.

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

Fields

image_identifier: Option<String>

The image to launch, or None for the one Sandbox::build_image built.

An image ARN, or a bare image name, which Sandbox::run resolves to its ARN with one ListMicrovmImages read. A name no image carries is refused with ERR_PRECONDITION before anything launches.

image_version: Option<String>

imageVersion, or None for the image’s own latest active version.

Pinning is what makes a canary a canary: without it a launch takes whatever version is latest at the moment the call lands, which is not necessarily the one the caller just built. Paired with crate::control::ControlPlane::set_image_version_status it is also the rollback — set the bad version INACTIVE, re-pin here to the good one — and a version set INACTIVE refuses to launch when named here.

See crate::control::RunMicrovmRequest::image_version, which this forwards to.

execution_role_arn: Option<String>

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

agent_token: Option<String>

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

client_token: Option<String>

Persist this unique launch key before sending a request; reuse only for that same launch and identical parameters. None mints a fresh key. A stable key requires an explicit agent_token and identity=false so retries carry identical payloads.

launch_env: HashMap<String, String>

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

The daemon applies this under each request’s own env, so a per-exec value wins on a key both set. Empty by default, and an empty map produces byte-for-byte the payload this client always sent — a caller who never touches this field cannot be affected by the field existing.

It shares the token’s 4096-byte payload budget, and the check is local: crate::control::RunHookPayload::for_launch refuses an over-ceiling payload before any call, naming the byte count and how much of it the env is. That matters here more than for the token, because one bearer token has always fit with room to spare and a map of credentials does not.

identity: bool

Whether to generate and deliver a tunnel identity (#70 layer 3).

On, the launch generates two fresh x25519 seeds, delivers the VM’s seed and the host’s public key in the same payload as the token, and [RunOutcome]-equivalent state on the session keeps the crate::identity::TunnelIdentity — the host secret and the VM’s public pin — for tunnel --verify-identity to prove the far end. Off (the default) sends byte-for-byte the payload this client always sent.

A flag rather than always-on, deliberately: the material spends 137 bytes of the payload’s measured 4096-byte budget, and a caller near the ceiling with a launch env deserves to choose which feature gets the room.

egress: bool

Whether to request the egress connector. Off omits it from the request; measured 2026-09-12 the platform gave a connector-less VM outbound network anyway (docs/PLATFORM.md).

egress_network_connectors: Vec<String>

Customer-managed Lambda VPC egress connector ARNs. See RunMicrovmRequest::egress_network_connectors.

deny_egress: bool

Sets advisory proxy-deny environment variables for clients that honor them. Workloads can bypass these variables. Internet isolation requires a VPC egress connector using a VPC without an internet gateway or NAT gateway.

Refused with RunRequest::egress. Existing caller-supplied proxy variables win; the added variables share the 4096-byte run-hook payload budget.

shell: bool

Whether to launch shell-capable: the ingress set becomes the measured pair [HTTP_INGRESS, SHELL_INGRESS] instead of ALL_INGRESS, which is what CreateMicrovmShellAuthToken requires and what microvm shell attaches to. Off (the default) launches byte-for-byte what this client always sent.

max_idle_sec: u32

idlePolicy.maxIdleDurationSeconds.

suspended_sec: u32

idlePolicy.suspendedDurationSeconds: how long a VM the idle policy suspended lasts before the service terminates it. An explicit suspend isn’t held to it (STATE-12).

auto_resume: bool

idlePolicy.autoResumeEnabled.

max_duration_sec: u32

maximumDurationInSeconds, checked against 1..=28800 before the call.

ready_timeout: Duration

How long to wait for RUNNING. The wait for the daemon to answer, after it, is crate::session::DEFAULT_BOOTSTRAP_TIMEOUT.

token_scope: Option<String>

A label for the run token (TRAP-1). Never the token.

logging: Option<Logging>

Per-VM logging (#201). See RunMicrovmRequest::logging.

wait: bool

Whether Sandbox::run waits for RUNNING and for the daemon to answer before returning (the default).

Off returns as soon as RunMicrovm is accepted, with the lifecycle still PENDING: the session is addressable, and Sandbox::wait_until_running finishes both waits later, from this process or after a durable workflow’s next step.

Implementations

impl RunRequest

pub fn new() -> RunRequest

A launch with the measured defaults: ingress only, ten-minute idle and suspended windows, a one-hour maximum duration, no auto-resume.

pub fn with_image(self, identifier: impl Into<String>) -> RunRequest

Launches identifier, an image ARN or a bare image name, rather than the built image.

pub fn with_egress(self) -> RunRequest

Requests the managed internet egress connector. Omission does not block internet access.

pub fn with_egress_network_connector(self, arn: impl Into<String>) -> RunRequest

Routes egress through a customer-managed Lambda network connector.

pub fn with_vpc_egress(self, arns: Vec<String>) -> RunRequest

Replaces managed internet egress with customer-managed VPC connectors, when any are given; an empty list leaves the request unchanged.

The two cannot be combined, so a launch surface that requests managed egress by default (an agent VM) uses this to switch rather than failing the launch.

pub fn with_deny_egress(self) -> RunRequest

Applies the advisory in-guest deny. See RunRequest::deny_egress for what it is and, more importantly, for what it is not.

pub fn egress_posture(&self) -> EgressPosture

What this launch’s outbound network is, as opposed to what it asked for.

The one derivation, so the CLI’s envelope, the CLI’s human line and any embedding consumer cannot disagree about the same launch.

pub fn effective_launch_env(&self) -> HashMap<String, String>

The launch environment as the guest will see it: the caller’s, plus the advisory proxy deny when RunRequest::deny_egress is on.

The caller’s own value wins on a shared key. A launch that already routes through a proxy of its own has said where its traffic goes, and overwriting that with a black hole would break a working configuration in the name of a posture this client already declines to call a seal.

pub fn with_shell(self) -> RunRequest

Requests a shell-capable launch. See RunRequest::shell.

pub fn with_image_version(self, version: impl Into<String>) -> RunRequest

Pins the launch to one imageVersion. See the field for why.

pub fn with_suspended_sec(self, seconds: u32) -> RunRequest

Sets idlePolicy.suspendedDurationSeconds, how long a VM the idle policy suspended lasts before the service terminates it. See RunRequest::suspended_sec.

pub fn with_agent_token(self, token: impl Into<String>) -> RunRequest

Reuses a caller-supplied agent token rather than minting one.

pub fn with_identity(self) -> RunRequest

Generates and delivers a tunnel identity with the launch (#70 layer 3).

After a run with this set, Sandbox::tunnel_identity holds what tunnel --verify-identity needs: the host’s secret and the VM’s public pin.

pub fn with_launch_env( self, key: impl Into<String>, value: impl Into<String>, ) -> RunRequest

Adds one launch-environment variable, which every exec in the VM starts with.

One pair per call rather than a whole map, because that is how a caller builds one — from flags, from a config file, one credential at a time — and a map-taking setter makes the second call silently discard the first. The field is public for a caller who really does hold a map.

Trait Implementations

impl Clone for RunRequest

fn clone(&self) -> RunRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RunRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for RunRequest

fn default() -> RunRequest

Returns the “default value” for a type.