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.

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 — the window STATE-12 refuses past.

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.

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 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 the wait later — from this process, or after a durable workflow’s next step.

Implementations

impl RunRequest

pub fn new() -> Self

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

Launches identifier rather than the built image.

pub fn with_egress(self) -> Self

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

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

Routes egress through a customer-managed Lambda network connector.

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

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

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

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

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

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

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

Sets the suspended window this sandbox will refuse a resume past (STATE-12).

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

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

pub fn with_identity(self) -> Self

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>, ) -> Self

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

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

Formats the value using the given formatter.

impl Default for RunRequest

fn default() -> Self

Returns the “default value” for a type.