Module microvm 

Launch, the launch wait, the lifecycle calls, and the proxy token (TRAP-5, TRAP-8).

TRAP-5: the payload ceiling is 4096 bytes, inclusive

RunHookPayload cannot hold an over-ceiling value, so the check happens when the payload is made rather than when the request is sent — which means every path into RunMicrovm is closed by one guard instead of each needing its own.

The number is worth stating precisely because the project got it wrong in the dangerous direction. docs/STRATEGY.md and docs/TRUST.md claimed 16 KB — and so does the service model’s own documentation string for runHookPayload, which reads “Maximum: 16,384 bytes” while its shape RunMicrovmRequestRunHookPayloadString says max: 4096. So a reader who checks the docs rather than the shape reproduces the bug. 4x wrong in the direction that tells a caller four times as much secret material fits as actually does. Bracketed 2026-08-07 by calling RunMicrovm with a deliberately bogus imageIdentifier so nothing could be created or billed: 4096 passes, 4097 fails.

Measured in UTF-8 bytes, not characters. A payload counted by character length passes while the same value with one multi-byte character in it does not.

TRAP-5’s other half: why the payload at all

It is the only per-VM secret channel the platform offers, and it is what keeps the agent token out of the shared image snapshot. That is safe because the platform forwards no external traffic until the run hook returns 200, so a per-VM secret delivered at launch wins the first-writer race through the endpoint.

The daemon reads it one JSON parse deeper than expected: the platform wraps the string, so the hook body is {"runHookPayload": "{\"agent_token\": \"...\"}"}.

TRAP-8: a terminal state before RUNNING

A VM that reaches a terminal state before RUNNING died during startup, and for a hook-serving daemon that almost always means a lifecycle hook failed. Polling through it wastes minutes and then reports a connection error that hides the cause — and by then the VM is gone, so stateReason is the only evidence left. ControlPlane::wait_for_running fails fast and attaches both the state and the reason.

TRAP-11, again: there is no shell-auth method here

ControlPlane::mint_auth_token calls CreateMicrovmAuthToken. There is no sibling for CreateMicrovmShellAuthToken, deliberately — see super.

Structs

Microvm

A launched MicroVM, as the service last described it.

ProxyToken

The minted proxy token, as a header map (TRAP-7).

RunHookPayload

A runHookPayload that is known to fit the service ceiling.

Constants

MAX_TOKEN_MINUTES

The service ceiling on a proxy token’s life, in minutes.

PROXY_AUTH_HEADER

The proxy token’s auth header, which is also the key in the authToken map.

PROXY_PORT_HEADER

The proxy port header.

SUSPEND_WANTED

The states a suspend may end in.