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 launch_env: HashMap<String, String>,
    pub identity: bool,
    pub 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>,
}

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.

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 means no outbound network.

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.

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 egress connector, which is what gives the VM outbound network.

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

Formats the value using the given formatter.

impl Default for RunRequest

fn default() -> Self

Returns the “default value” for a type.