Expand description
High-performance VM-backed AIXI environment using nyx-lite (Firecracker).
This module provides a VM environment implementation built on top of nyx-lite, enabling high-frequency snapshot-based resets for fast experimentation (hardware and guest behavior dependent).
§Architecture
The environment uses Firecracker’s KVM-based microVM with nyx-lite’s incremental snapshot and reset capabilities. Communication with the guest occurs via:
- Shared Memory: Zero-copy data transfer between host and guest
- Hypercalls: Control plane communication (snapshot, done, etc.)
- Serial PTY: Optional console I/O for simpler protocols
§Design Principles
- Universal: Not biased towards any specific use case (fuzzing, etc.)
- High Performance: Leverages incremental snapshots and dirty page tracking
- Configurable: Pluggable reward policies, action sources, observation modes
- Information-Theoretic: Built-in support for entropy-based metrics
Structs§
- NyxAction
Filter - Information-theoretic action filtering.
- NyxAction
Spec - A single action specification.
- NyxFuzz
Config - Fuzzing configuration for action generation.
- NyxProtocol
Config - Protocol configuration for structured communication.
- NyxSnapshot
- NyxStep
Result - Result of a single environment step.
- NyxTrace
Config - Configuration for trace collection and analysis.
- NyxVM
- NyxVm
Config - Complete configuration for the nyx-lite VM environment.
- NyxVm
Environment - High-performance VM environment using nyx-lite.
- Shared
Memory Region - A contiguous guest memory region exposed for sharing with the host.
Enums§
- Exit
Reason - Fuzz
Mutator - Fuzzing mutator types.
- NyxAction
Source - Source of actions for the environment.
- NyxExit
Kind - Simplified exit reason categories.
- NyxObservation
Policy - How observations are derived from guest output.
- NyxObservation
Stream Mode - Stream normalization mode.
- NyxReward
Policy - How rewards are computed.
- NyxReward
Shaping - Optional reward shaping (additive to base reward).
- Payload
Encoding - Payload encoding for wire protocol.
- Shared
Memory Policy - Control whether shared memory pages are snapshotted or preserved across resets.
Constants§
- HYPERCALL_
DBGPRINT - HYPERCALL_
EXECDONE - Hypercall identifiers (must match guest implementation). These are exported for use by custom guest programs.
- HYPERCALL_
NYX_ LITE - HYPERCALL_
SHAREMEM - HYPERCALL_
SNAPSHOT