Crate microsandbox_protocol 

microsandbox-protocol defines the shared protocol types used for communication between the host and the guest agent over CBOR-over-virtio-serial.

For how the protocol is versioned and evolved while staying backward compatible across independently-upgraded hosts and live sandboxes, see VERSIONING.md in this crate.

Modules

codec

Length-prefixed frame codec for reading and writing protocol messages.

core

Core protocol message payloads.

exec

Exec-related protocol message payloads.

fs

Filesystem-related protocol message payloads.

heartbeat

Heartbeat data for the guest agent.

message

Message envelope and type definitions for the agent protocol.

tcp

TCP stream protocol message payloads.

Enums

ProtocolError

Errors that can occur during protocol operations.

Constants

AGENT_PORT_NAME

Virtio-console port name for the agent channel.

AGENT_RELAY_ID_RANGE_STEP

Size of the correlation ID range allocated to each relay client.

AGENT_RELAY_MAX_CLIENTS

Maximum number of simultaneous SDK clients the host relay admits.

ENV_BLOCK_ROOT

Environment variable specifying how agentd assembles the root filesystem.

ENV_DIR_MOUNTS

Environment variable carrying virtiofs directory volume mount specs for guest init.

ENV_DISK_MOUNTS

Environment variable carrying disk-image volume mount specs for guest init.

ENV_FILE_MOUNTS

Environment variable carrying virtiofs file volume mount specs for guest init.

ENV_HANDOFF_INIT

Environment variable selecting a guest init binary for PID 1 handoff.

ENV_HANDOFF_INIT_ARGS

Argv list for the handoff init binary.

ENV_HANDOFF_INIT_ENV

Extra environment variables for the handoff init binary.

ENV_HOSTNAME

Environment variable carrying the guest hostname for agentd.

ENV_HOST_ALIAS

Environment variable carrying the DNS name the guest uses to reach the sandbox host (Docker’s host.docker.internal equivalent).

ENV_NET

Environment variable carrying the guest network interface configuration.

ENV_NET_IPV4

Environment variable carrying the guest IPv4 network configuration.

ENV_NET_IPV6

Environment variable carrying the guest IPv6 network configuration.

ENV_RLIMITS

Environment variable carrying sandbox-wide resource limits.

ENV_SECURITY_PROFILE

Environment variable carrying the sandbox in-guest security profile.

ENV_TMPFS

Environment variable carrying tmpfs mount specs for guest init.

ENV_USER

Environment variable carrying the default guest user for agentd execs.

FILE_MOUNTS_DIR

Guest directory for file mount virtiofs shares.

GUEST_TLS_CA_PATH

Guest-side path to the CA certificate for TLS interception.

GUEST_TLS_HOST_CAS_PATH

Guest-side path to a PEM bundle of the host’s extra trusted CAs.

HANDOFF_INIT_AUTO

Sentinel value for ENV_HANDOFF_INIT requesting auto-detection.

HANDOFF_INIT_AUTO_CANDIDATES

Ordered list of init-binary paths agentd probes when ENV_HANDOFF_INIT is set to HANDOFF_INIT_AUTO.

HANDOFF_INIT_SEP

Separator byte for argv/env entries in handoff-init env vars.

HANDOFF_INIT_SEP_STR

String form of HANDOFF_INIT_SEP for use with &str-friendly APIs like [T]::join. Avoids per-call char.to_string() allocations on the host’s encoder side.

HANDOFF_POWEROFF_TIMEOUT

Maximum time agentd spends in its handoff-mode poweroff sequence.

RUNTIME_FS_TAG

Virtiofs tag for the runtime filesystem (scripts, heartbeat).

RUNTIME_MOUNT_POINT

Guest mount point for the runtime filesystem.

SCRIPTS_PATH

Guest path for named scripts (added to PATH by agentd).

SHUTDOWN_FLUSH_TIMEOUT

How long the host waits after forwarding core.shutdown to agentd before triggering its own VMM exit fallback.

Type Aliases

ProtocolResult

The result type for protocol operations.