Inside VidyaX: Building a Gas-Metered Bytecode VM in Rust for Sandboxed AI Agents
Why letting AI coding agents run arbitrary bash scripts is fragile and slow—and how a custom 5-byte bytecode VM with virtualized I/O makes procedural execution deterministic and safe.
Why AI Agents Need a Micro-Sandbox Instead of Raw Shell Execution
Most AI coding agents execute every quick calculation, data transformation, or verification probe by spawning a full OS shell (`bash`, `python3`, or `node`). That approach is slow (tens to hundreds of milliseconds per fork), non-deterministic across Linux/macOS/Windows, and dangerous if an agent hallucinates a destructive command or infinite loop.
In Kronumos, we built **VidyaX (`vxvm`)**—an embedded, gas-metered bytecode virtual machine written in Rust with a companion 110 KB WebAssembly target (`vidyax.wasm`) for the browser workbench. Instead of trusting arbitrary host shells for deterministic computation and procedural rollouts, VidyaX executes compact `.vxb` bytecode in microsecond-latency isolated memory with zero shell side effects.
Deny-by-Default Resource & Security Bounds
Every VidyaX execution runs under explicit, hard-enforced `VidyaxOptions` limits before a single instruction is dispatched. Even if an agent generates an infinite `while` loop or memory bomb, the VM halts cleanly without freezing the terminal or leaking host state.
- Instruction Gas Metering (`max_instr: 1_000_000`): every dispatched opcode decrements the remaining gas budget, guaranteeing termination.
- Bounded Memory (`max_mem_bytes: 32 MiB`) and wall-clock timeout (`max_time_secs: 10`).
- Deny-by-Default I/O (`allow_fs: false`, `allow_net: false`): filesystem and network capabilities are off unless explicitly granted, and `KRONUMOS_AIR_GAPPED=1` / `KRONUMOS_OFFLINE=1` unconditionally forces `allow_net = false`.
- Private RAII Temp Isolation: when host staging is needed, `PrivateVxTempDir` creates `0o700` directories and `0o600` files that are wiped automatically on `Drop`.
The Compact 5-Byte `.vxb` Bytecode Format
To store procedural algorithms compactly inside Kronumos Knowledge Crystals and execute them with minimal decoding overhead, VidyaX defines a fixed-width binary packet format: a 4-byte `VIDYAX_MAGIC` header followed by a stream of 5-byte instructions (`1-byte opcode` + `4-byte little-endian i32 operand`).
Fixed-width 5-byte instructions make validation (`body.len() % 5 == 0`), jump-target bounds checking, and linear decoding trivial and O(N) safe against malformed inputs.
// Header: [4 bytes VIDYAX_MAGIC] + N * [1 byte opcode | 4 bytes i32 LE operand]
PushConst = 0x01 LoadVar = 0x02 StoreVar = 0x03
Add = 0x10 Sub = 0x11 Mul = 0x12 Div = 0x13
CmpEq = 0x20 CmpLt = 0x21 CmpGt = 0x22
Jmp = 0x30 Jz = 0x31 Call = 0x32 Ret = 0x33
VfsRead = 0x40 VfsWrite = 0x41 VnetFetch = 0x42
Halt = 0xFFZero-Side-Effect Rollouts With VirtualIoEnv
Notice opcodes `0x40`–`0x42` (`VfsRead`, `VfsWrite`, `VnetFetch`). Rather than touching your real filesystem or hitting live HTTP endpoints during exploratory planning or MCTS rollouts, VidyaX binds those opcodes to `VirtualIoEnv`—a pure in-memory `BTreeMap<String, String>` virtual filesystem (`vfs`) and mock response map (`vnet_mocks`).
That allows Kronumos to simulate and verify multi-step procedural logic safely in RAM before ever touching a real file on disk. And because the same VM compiles to a 110 KB `vidyax.wasm` module, the browser workbench at `kronumos.com/chat` shares the exact same execution semantics as the native Rust CLI.
“Embedding a gas-metered, virtual-I/O bytecode VM inside a coding agent turns speculative script execution from an OS security risk into a microsecond deterministic primitive.”
Frequently Asked Questions
Does VidyaX replace bash or cargo/pytest for running real project tests?
No. Real repository verification still runs your actual test runner (`cargo test`, `pytest`, `npm test`, `go test`). VidyaX handles isolated micro-sandboxed computation, procedural crystal bindings, and zero-side-effect in-memory rollouts.
Can VidyaX run in the browser as well as the Rust CLI?
Yes. VidyaX ships both inside the native Rust CLI (`kronumos-core`) and as a 110 KB WebAssembly module (`vidyax.wasm`) for the Kronumos web workbench.
Audit your repository in milliseconds with zero LLM calls
Run native Rust Tree-sitter AST checks on Linux, macOS, and Windows PowerShell, or test in the browser.