Crate microvms_protocol 

The microvms-agentd wire contract as types, shared by the daemon and every Rust client of it.

Why this is a crate rather than a copy on each side

The daemon serializes these shapes and a client deserializes them, and for as long as each side owned its own definitions the only thing keeping them in step was review. That is the failure mode docs/schema.json was built to catch after the fact; this crate makes the class of error unavailable in the first place. A field renamed here breaks compilation on whichever side has not caught up, which is the earliest and cheapest place a protocol change can fail.

What lives here and what does not

Pure data only: serde plus schemars, no tokio, no axum, no base64. The rule is whether the type is what travels or machinery for making it travel. So the SSE event payloads are here and the stream that emits them is not; the base64 field is here as a String and the encoding is in the daemon’s handler; the error body is here and the fail(status, slug, detail) helper that pairs it with an axum StatusCode is not.

Every type derives both Serialize and Deserialize even where one side needs only one of them, because the missing half is exactly what a client would have to hand-write. docs/schema.json is generated from these attributes under both contracts and byte-compared in CI, so a shape that reads differently than it writes is a test failure rather than a consumer’s problem.

Modules

discovery

Additive discovery, separate from the published exhaustive health response.

exec

Exec wire types: the bodies, queries, and SSE event payloads of /v1/exec/*.

fs

File-transfer wire types: the one query string every /v1/fs/* route takes.

health

The GET /v1/health response.

hook

Lifecycle-hook wire types and the prefix the platform calls them under.

identity

The tunnel’s identity proof: the seed’s wire contract, the Noise pattern, and the pin.

tunnel

The TCP relay’s wire types and close codes.

Constants

DEFAULT_AGENT_PORT

The daemon listener port when AGENTD_PORT is unset.

PROTOCOL_VERSION

Protocol version, distinct from the daemon version.

VERSION_HEADER

The response header carrying the daemon version, on every response including errors.