Skip to content
All Engineering Articles
DEEP DIVE #01||VM & COMPILERS|10 MIN READ

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.

Author
Muhammad Naufal Daffa
Chief Technology Officer (CTO), Tokenectomy Labs

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.

VidyaX `.vxb` Opcode Table (src/vidyax_bridge.rs)5-Byte Fixed ISA
// 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      = 0xFF

Zero-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.

Key Takeaway

“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.

Try Kronumos v1.3.0

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.

Related Reading