Struct RunMicrovmRequest 

pub struct RunMicrovmRequest {

    pub image_identifier: String,
    pub image_version: Option<String>,
    pub execution_role_arn: Option<String>,
    pub connectors: Vec<ConnectorIntent>,
    pub egress_network_connectors: Vec<String>,
    pub run_hook_payload: RunHookPayload,
    pub max_duration_sec: u32,
    pub max_idle_sec: u32,
    pub suspended_sec: u32,
    pub auto_resume: bool,
    pub token_scope: Option<String>,
    pub client_token: Option<String>,
    pub logging: Option<Logging>,
}

Everything RunMicrovm needs.

run_hook_payload is a RunHookPayload, which cannot hold an over-ceiling value — so TRAP-5 is closed before this struct exists rather than checked when it is used.

Fields

image_identifier: String

The image ARN or ID to launch.

image_version: Option<String>

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

The launch half of blue/green

None is what this client always sent, and it means “whatever latestActiveImageVersion is now” — which is right for the ordinary case and wrong for the two that matter. A canary wants to launch against exactly the version it is testing, not against whatever became latest while it was starting. And a rollback wants to re-pin to the known-good version, which “latest” cannot express at all once a bad version is the latest one.

With ControlPlane::set_image_version_status the three moves compose: build v2, canary-launch pinned to v2, and on failure set v2 INACTIVE and re-pin to v1. A version set INACTIVE refuses to launch when pinned here, which is what makes the retire real rather than advisory.

Checked against the Version shape before the call — see require_valid_version on why a rollback is the worst moment for a rejection about the request.

execution_role_arn: Option<String>

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

connectors: Vec<ConnectorIntent>

The connectors to request, as intents (TRAP-4). Ingress is required for a session to work at all; omitting egress omits the connector from the request (measured 2026-09-12: the platform gave the VM outbound network anyway, docs/PLATFORM.md).

egress_network_connectors: Vec<String>

Customer-managed Lambda VPC egress connector ARNs, created through lambda-core. Cannot be combined with ConnectorIntent::Egress. Internet isolation requires a VPC without an internet gateway or NAT gateway; an ARN alone proves no isolation.

run_hook_payload: RunHookPayload

The already-validated payload carrying the agent token.

max_duration_sec: u32

maximumDurationInSeconds, checked against 1..=28800 when the request is sent.

max_idle_sec: u32

idlePolicy.maxIdleDurationSeconds, checked against the model’s min: 60 before the call.

This comment used to say the guard was deliberately absent, because min is one of the four keys botocore’s VALIDATED_METADATA_ATTRS enforces locally. True of botocore, and this client never touches it — see require_idle_duration. 59 reached the wire.

suspended_sec: u32

idlePolicy.suspendedDurationSeconds.

The model’s min is 0, so every u32 satisfies it and there is no guard — an absence with a reason rather than an oversight, and the drift gate pins the 0 so a future floor is noticed. Its ceiling is unstated.

The requested value drives the local resume window. The service also reports its active policy in Microvm::idle_policy.

auto_resume: bool

idlePolicy.autoResumeEnabled.

token_scope: Option<String>

A label for the run token, defaulting to the image identifier (TRAP-1).

client_token: Option<String>

Optional durable launch idempotency key. Reuse only for retries of one launch, with identical parameters and run-hook payload. None preserves fresh defaults. Never derive this from an image name or reuse it for a different VM.

logging: Option<Logging>

Per-VM logging: a CloudWatch group (and optional exact stream) or disabled. None leaves the service’s default destination in place (#201).

Implementations

impl RunMicrovmRequest

pub fn new( image_identifier: impl Into<String>, run_hook_payload: RunHookPayload, ) -> 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_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_shell(self) -> Self

Requests a shell-capable launch: the ingress set becomes the measured pair, [HTTP_INGRESS, SHELL_INGRESS].

Replaces ALL_INGRESS rather than adding beside it, because the platform forbids the combination and says so only at token-mint time — the VM launches, reaches RUNNING, and bills before the failure appears (docs/PLATFORM.md, 2026-08-15). [HTTP_INGRESS, SHELL_INGRESS] is the set measured to both launch and mint a shell token, and HTTP_INGRESS stays in the pair so the daemon endpoint keeps working. Egress is untouched: shell access and outbound network are separate questions.

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

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

Trait Implementations

impl Clone for RunMicrovmRequest

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 RunMicrovmRequest

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

Formats the value using the given formatter.