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 when CUDA-over-vsock is available.
27///
28/// The guest agent uses it to stage the bundled CUDA shims into workload
29/// containers and the runtime shim uses it to enable guest-RAM zero-copy.
30pub const CUDA_ZEROCOPY: &str = "SMOLVM_CUDA_ZEROCOPY";
31
32/// The VM was started as a live-fork golden.
33///
34/// The guest agent uses this to expose the workload-facing forkpoint helper.
35/// Fork clones inherit the already-running helper from the golden snapshot.
36pub const FORKABLE: &str = "SMOLVM_FORKABLE";
37
38/// Planned CUDA fork-pool size passed to the guest agent.
39///
40/// The agent uses this to select fork-friendly workload defaults only when a
41/// pool was explicitly declared; ordinary CUDA machines are unaffected.
42pub const CUDA_FORK_POOL_SIZE: &str = "SMOLVM_CUDA_FORK_POOL_SIZE";
43
44/// Workload override for automatic PyTorch expandable segments.
45///
46/// A declared CUDA fork pool enables the policy by default. Setting this to
47/// `0`, `false`, `off`, or `no` in the workload environment disables it.
48pub const CUDA_EXPANDABLE_SEGMENTS: &str = "SMOLVM_CUDA_EXPANDABLE_SEGMENTS";
49
50/// Env var the host sets on guest init to signal Rosetta 2 x86_64 translation
51/// was requested (and is available on the host).
52///
53/// Present means the host has attached the RosettaLinux runtime as the virtiofs
54/// tag [`crate::ROSETTA_TAG`]; the guest agent reads this on startup and, if set,
55/// mounts that runtime at [`crate::ROSETTA_GUEST_PATH`] and registers the ptrace
56/// wrapper with `binfmt_misc` as the interpreter for x86_64 ELF binaries. Absent
57/// means no Rosetta was requested.
58///
59/// This is a boolean sentinel — the value is [`VALUE_ON`] when set.
60pub const ROSETTA: &str = "SMOLVM_ROSETTA";
61
62/// Filename of this VM's readiness marker, written by the agent into the virtiofs
63/// rootfs when boot completes. Per VM (so concurrent boots don't race on one
64/// shared file); the host pre-creates and polls the same name. Unset → the agent
65/// falls back to the shared [`crate::AGENT_READY_MARKER`] constant.
66pub const READY_MARKER: &str = "SMOLVM_READY_MARKER";
67
68/// Host wall-clock at VM launch, nanoseconds since the Unix epoch. The agent
69/// uses this to set the guest clock when the hypervisor gives the guest no
70/// readable paravirt clock (e.g. WHP on Windows, where the guest otherwise
71/// boots at ~1999 and every TLS cert validation fails). The agent only applies
72/// it when the guest clock already looks obviously wrong, so it never fights an
73/// accurate kvmclock (Linux/KVM) or HVF-seeded RTC (macOS).
74pub const HOST_TIME_NS: &str = "SMOLVM_HOST_TIME_NS";
75
76/// Selects whether the guest should configure a real virtio NIC.
77pub const BACKEND: &str = "SMOLVM_NETWORK_BACKEND";
78/// Canonical backend value meaning "configure guest virtio-net".
79pub const BACKEND_VIRTIO_NET: &str = "virtio-net";
80/// Guest IPv4 address.
81pub const GUEST_IP: &str = "SMOLVM_NETWORK_GUEST_IP";
82/// Guest-visible default gateway IPv4 address.
83pub const GATEWAY: &str = "SMOLVM_NETWORK_GATEWAY";
84/// Guest subnet prefix length.
85pub const PREFIX_LEN: &str = "SMOLVM_NETWORK_PREFIX_LEN";
86/// Guest MAC address in colon-separated string form.
87pub const GUEST_MAC: &str = "SMOLVM_NETWORK_GUEST_MAC";
88/// Guest IPv6 (ULA) address. Optional: absent means IPv4-only guest config.
89pub const GUEST_IP6: &str = "SMOLVM_NETWORK_GUEST_IP6";
90/// Guest-visible default gateway IPv6 address.
91pub const GATEWAY6: &str = "SMOLVM_NETWORK_GATEWAY6";
92/// Guest IPv6 prefix length.
93pub const PREFIX_LEN6: &str = "SMOLVM_NETWORK_PREFIX_LEN6";
94/// Guest-visible DNS server IPv4 address.
95pub const DNS: &str = "SMOLVM_NETWORK_DNS";
96/// Enables the guest-side DNS filtering proxy.
97pub const DNS_FILTER: &str = "SMOLVM_DNS_FILTER";
98/// Enables the guest-side Docker socket bridge: the agent listens on the
99/// `ports::DOCKER` vsock port and proxies each connection to the in-guest
100/// Docker daemon socket, so the host can reach it over a Unix socket.
101pub const DOCKER_SOCKET: &str = "SMOLVM_DOCKER_SOCKET";
102
103/// Carries the user's published Unix-socket bridges to the guest agent, encoded
104/// by [`crate::publish_socket::encode`] (`port|dir|guest_path;…`). The agent
105/// decodes it on startup and spawns one relay per entry. Absent means none.
106pub const PUBLISH_SOCKETS: &str = "SMOLVM_PUBLISH_SOCKETS";
smolvm_protocol/guest_env.rs

smolvm_protocol/
guest_env.rs
