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/// Filename of this VM's readiness marker, written by the agent into the virtiofs
27/// rootfs when boot completes. Per VM (so concurrent boots don't race on one
28/// shared file); the host pre-creates and polls the same name. Unset → the agent
29/// falls back to the shared [`crate::AGENT_READY_MARKER`] constant.
30pub const READY_MARKER: &str = "SMOLVM_READY_MARKER";
31
32/// Host wall-clock at VM launch, nanoseconds since the Unix epoch. The agent
33/// uses this to set the guest clock when the hypervisor gives the guest no
34/// readable paravirt clock (e.g. WHP on Windows, where the guest otherwise
35/// boots at ~1999 and every TLS cert validation fails). The agent only applies
36/// it when the guest clock already looks obviously wrong, so it never fights an
37/// accurate kvmclock (Linux/KVM) or HVF-seeded RTC (macOS).
38pub const HOST_TIME_NS: &str = "SMOLVM_HOST_TIME_NS";
39
40/// Selects whether the guest should configure a real virtio NIC.
41pub const BACKEND: &str = "SMOLVM_NETWORK_BACKEND";
42/// Canonical backend value meaning "configure guest virtio-net".
43pub const BACKEND_VIRTIO_NET: &str = "virtio-net";
44/// Guest IPv4 address.
45pub const GUEST_IP: &str = "SMOLVM_NETWORK_GUEST_IP";
46/// Guest-visible default gateway IPv4 address.
47pub const GATEWAY: &str = "SMOLVM_NETWORK_GATEWAY";
48/// Guest subnet prefix length.
49pub const PREFIX_LEN: &str = "SMOLVM_NETWORK_PREFIX_LEN";
50/// Guest MAC address in colon-separated string form.
51pub const GUEST_MAC: &str = "SMOLVM_NETWORK_GUEST_MAC";
52/// Guest IPv6 (ULA) address. Optional: absent means IPv4-only guest config.
53pub const GUEST_IP6: &str = "SMOLVM_NETWORK_GUEST_IP6";
54/// Guest-visible default gateway IPv6 address.
55pub const GATEWAY6: &str = "SMOLVM_NETWORK_GATEWAY6";
56/// Guest IPv6 prefix length.
57pub const PREFIX_LEN6: &str = "SMOLVM_NETWORK_PREFIX_LEN6";
58/// Guest-visible DNS server IPv4 address.
59pub const DNS: &str = "SMOLVM_NETWORK_DNS";
60/// Enables the guest-side DNS filtering proxy.
61pub const DNS_FILTER: &str = "SMOLVM_DNS_FILTER";
smolvm_protocol/guest_env.rs

smolvm_protocol/
guest_env.rs
