smolvm_protocol/
guest_env.rs

1//! Shared environment-variable contract between the host launcher and guest agent.
2//!
3//! These names form the protocol boundary between:
4//! - the host-side launcher, which decides what features to enable
5//! - the guest agent, which reads these vars on startup and acts accordingly
6//!
7//! They should be treated as stable protocol constants rather than ad hoc
8//! launcher strings.
9
10/// Standard "enabled" value for boolean `SMOLVM_*` sentinel env vars.
11///
12/// The host writes this when a feature is enabled; the guest agent
13/// compares against it. A single canonical value prevents `true` / `yes` /
14/// `1` mismatches between the two sides.
15pub const VALUE_ON: &str = "1";
16
17/// Env var the host sets on guest init to signal GPU acceleration was requested.
18///
19/// Present means "host asked for GPU"; the guest agent reads this and emits a
20/// post-boot sanity log confirming whether `/dev/dri/*` nodes actually appeared.
21/// Absent means no GPU was requested.
22///
23/// This is a boolean sentinel — the value is [`VALUE_ON`] when set.
24pub const GPU: &str = "SMOLVM_GPU";
25
26/// Env var the host sets on guest init to signal Rosetta 2 x86_64 translation
27/// was requested (and is available on the host).
28///
29/// Present means the host has attached the RosettaLinux runtime as the virtiofs
30/// tag [`crate::ROSETTA_TAG`]; the guest agent reads this on startup and, if set,
31/// mounts that runtime at [`crate::ROSETTA_GUEST_PATH`] and registers the ptrace
32/// wrapper with `binfmt_misc` as the interpreter for x86_64 ELF binaries. Absent
33/// means no Rosetta was requested.
34///
35/// This is a boolean sentinel — the value is [`VALUE_ON`] when set.
36pub const ROSETTA: &str = "SMOLVM_ROSETTA";
37
38/// Filename of this VM's readiness marker, written by the agent into the virtiofs
39/// rootfs when boot completes. Per VM (so concurrent boots don't race on one
40/// shared file); the host pre-creates and polls the same name. Unset → the agent
41/// falls back to the shared [`crate::AGENT_READY_MARKER`] constant.
42pub const READY_MARKER: &str = "SMOLVM_READY_MARKER";
43
44/// Host wall-clock at VM launch, nanoseconds since the Unix epoch. The agent
45/// uses this to set the guest clock when the hypervisor gives the guest no
46/// readable paravirt clock (e.g. WHP on Windows, where the guest otherwise
47/// boots at ~1999 and every TLS cert validation fails). The agent only applies
48/// it when the guest clock already looks obviously wrong, so it never fights an
49/// accurate kvmclock (Linux/KVM) or HVF-seeded RTC (macOS).
50pub const HOST_TIME_NS: &str = "SMOLVM_HOST_TIME_NS";
51
52/// Selects whether the guest should configure a real virtio NIC.
53pub const BACKEND: &str = "SMOLVM_NETWORK_BACKEND";
54/// Canonical backend value meaning "configure guest virtio-net".
55pub const BACKEND_VIRTIO_NET: &str = "virtio-net";
56/// Guest IPv4 address.
57pub const GUEST_IP: &str = "SMOLVM_NETWORK_GUEST_IP";
58/// Guest-visible default gateway IPv4 address.
59pub const GATEWAY: &str = "SMOLVM_NETWORK_GATEWAY";
60/// Guest subnet prefix length.
61pub const PREFIX_LEN: &str = "SMOLVM_NETWORK_PREFIX_LEN";
62/// Guest MAC address in colon-separated string form.
63pub const GUEST_MAC: &str = "SMOLVM_NETWORK_GUEST_MAC";
64/// Guest IPv6 (ULA) address. Optional: absent means IPv4-only guest config.
65pub const GUEST_IP6: &str = "SMOLVM_NETWORK_GUEST_IP6";
66/// Guest-visible default gateway IPv6 address.
67pub const GATEWAY6: &str = "SMOLVM_NETWORK_GATEWAY6";
68/// Guest IPv6 prefix length.
69pub const PREFIX_LEN6: &str = "SMOLVM_NETWORK_PREFIX_LEN6";
70/// Guest-visible DNS server IPv4 address.
71pub const DNS: &str = "SMOLVM_NETWORK_DNS";
72/// Enables the guest-side DNS filtering proxy.
73pub const DNS_FILTER: &str = "SMOLVM_DNS_FILTER";
74/// Enables the guest-side Docker socket bridge: the agent listens on the
75/// `ports::DOCKER` vsock port and proxies each connection to the in-guest
76/// Docker daemon socket, so the host can reach it over a Unix socket.
77pub const DOCKER_SOCKET: &str = "SMOLVM_DOCKER_SOCKET";
smolvm_protocol/guest_env.rs

smolvm_protocol/
guest_env.rs
