Research / Systems Test
Building LAN-VM-BRIDGE for Isolated Local AI
I built a private-network test bench that routes browser chat through a VirtualBox host and an isolated guest VM before reaching a local Ollama model.
Published on
Architecture
A browser controller, VM host agent, guest agent, and Ollama instance connected through three separate runtime roles.
Verified Path
Eight unit tests passed, followed by a live end-to-end model response through both VirtualBox roles in about 6 seconds.
Project Scope
LAN-VM-BRIDGE is a local systems research bench with a working browser-to-VM relay, automated guest startup, and streamed model responses. It is built for a trusted private-network lab.
Why I Built It
I wanted to test whether a local language model could remain isolated inside a virtual machine without losing a usable browser chat workflow. Instead of letting the controller call Ollama directly, every message has to cross a series of defined machine and network boundaries.
The implementation centers on orchestration. It connects a host, starts or selects a guest VM, moves jobs through each role, streams the response back, and detects unavailable guests.
The Three Runtime Roles
The main-machine folder contains a Node controller and a small browser chat. It queues jobs for connected VM hosts and sends live updates to the browser with server-sent events.
The vm-host-machine folder runs on the physical computer that owns VirtualBox. Its agent connects outward to the controller, manages VM startup, and provides a token-protected corridor that guest machines can reach.
The guest-vm folder runs beside Ollama inside the isolated VM. The guest agent polls for work, sends the conversation to the local model, and returns response chunks through the host agent. The controller and host agent route content, but they do not generate the answer.
A One-PC VirtualBox Lab
The repository also includes a one-PC lab so the complete three-role path can be tested without three physical computers. The controller and a small hypervisor adapter run on the Windows host. One VirtualBox VM acts as the VM host role, while a second VM runs the guest agent and Ollama.
Clicking Start VM creates a fresh linked guest clone from a prepared snapshot. The lab waits for VirtualBox Guest Additions, launches the guest role, and then makes the model available to the browser. Recreating the runtime guest from a known template makes repeat tests easier and prevents an old guest state from quietly becoming part of the result.
Private Network Boundaries
The controller and host corridor bind to loopback by default. Private LAN and VirtualBox host-only addresses are supported, while an unsafe public bind is rejected unless it is deliberately enabled in local configuration.
Agent requests use a shared bridge token stored in ignored local environment files. The repository also ignores logs, runtime state, VM disks, snapshots, keys, certificates, and generated lab credentials. Model responses are token-bounded so one long generation cannot block the guest worker indefinitely.
Testing the Full Relay
The public release includes focused tests for configuration parsing, message validation, VirtualBox clone arguments, guest startup, Guest Additions readiness, bounded Ollama requests, and stale guest detection. All eight tests passed during this release check.
I also ran the live smoke test with both lab VMs online. The prompt traveled from the controller to the host role, through the guest role, into Ollama, and back through the same path. The expected response returned in 6.029 seconds. That is one local verification run, not a formal latency benchmark.
What This Experiment Showed
Isolating a model is only one part of the problem. A usable system also needs startup coordination, heartbeats, stale-worker handling, bounded jobs, streaming, and a repeatable way to rebuild the runtime environment.
LAN-VM-BRIDGE makes the local message path visible, testable, and reproducible. Its lab design uses an in-memory controller queue and a trusted local guest worker. Deployment remains scoped to a private lab, not public internet exposure or multi-tenant hosting.