aido-vm · agent's body, sandboxed

Give your agent a VM,
not your desktop.

aido-vm hands an LLM full control of a QEMU/KVM virtual machine via 29 MCP tools · screenshot, click, type, scroll, OCR, snapshot, lifecycle. Anthropic computer-use parity, plus everything the host-only spec can't do.

The agent has no limit inside the VM. The VM has no reach outside itself: KVM-isolated, snapshot-rewindable in 2 s, loopback-only by default.

read the 29 tools → github
29
MCP tools
~2s
snapshot revert
~200ms
pool acquire
~256MB
per body
aido-vm · ubuntu-alpine
$ aido-vm shot
✓ captured 1024×768 png
$ aido-vm click 460 590
✓ button{Login}
$ aido-vm type "agent@x.co"
✓ 11 chars typed
$ aido-vm wait_for_text "Welcome"
✓ "Welcome, agent"
$ aido-vm snapshot_create checkpoint
✓ saved in 1.8s
vnc · 127.0.0.1:5901 ● running · 1 agent
the killer combo

Unlimited agency, fully rewindable.

Computer-use agents are powerful and dangerous on a host. aido-vm keeps the power, neutralises the danger.

inside the VM

No limit

The agent is root in its own machine. It can:

  • run any shell command, install any package
  • open a browser, log in, fill forms, click links
  • type Unicode, use modifier chords, scroll, drag
  • read with OCR, wait for text to appear
  • spawn sub-processes, daemons, X servers
outside the VM

No reach

The VM cannot touch the host. By default:

  • KVM kernel isolation (separate /proc, devices)
  • network = SLIRP NAT, outbound only, no LAN
  • VNC bound to 127.0.0.1 · never reachable from elsewhere
  • libvirt qemu:///session · runs as your user, never root
  • snapshot revert ~2 s = any catastrophe undoable
architecture

Two paths, same toolbelt.

aido-vm exposes itself as an MCP server. Wire it directly into any MCP client · or through the AIDO orchestrator gateway alongside aido-runtime + aido-browser, for a unified 101-tool surface.

┌── LLM (Claude · Codex · Cursor · Ollama) │ │ MCP / stdio (json-rpc) ▼ ┌────────────────────────────────┐ ┌────────────────────────────────┐ │ Path A · direct │ OR │ Path B · orchestrator gateway │ │ │ │ │ │ ┌────────────────────────┐ │ │ ┌────────────────────────┐ │ │ │ aido-vm-mcp │ │ │ │ aido-orchestrator │ │ │ │ 29 vm_* tools │ │ │ │ 101 tools (58+29+14) │ │ │ └──────────┬─────────────┘ │ │ └──────────┬─────────────┘ │ │ ▼ │ │ ChildMcpClient spawns 3 │ │ ┌────────────────────────┐ │ │ downstreams: │ │ │ virsh / RFB / OCR │ │ │ aido-runtime · vm · browser │ │ └──────────┬─────────────┘ │ │ ▼ │ │ ▼ │ │ unified MCP surface │ │ ┌────────────────────────┐ │ │ │ │ │ QEMU/KVM live VM │ │ │ │ │ └────────────────────────┘ │ │ │ └────────────────────────────────┘ └────────────────────────────────┘
# .mcp.json · direct mode { "mcpServers": { "aido-vm": { "command": "aido-vm-mcp" } } } # .mcp.json · gateway mode (all three bodies on one connection) { "mcpServers": { "aido": { "command": "aido-orchestrator", "args": ["--mcp"], "env": { "AIDO_VM_DOWNSTREAM": "1" } } } }
tool catalog · 29 tools

Full Anthropic computer-use parity, plus VM ops.

All 13 actions of computer_20250124 (screenshot · click · key · type · scroll · drag · triple-click · cursor-position · wait …) plus 16 VM-level tools the host-only spec can't have: lifecycle, snapshots, OCR, pool.

display
vm_screenshot
PNG of the primary display.
mouse
vm_click
Left/right/middle click at (x, y).
mouse
vm_triple_click
Select a whole line of text.
mouse
vm_move
Move cursor without clicking.
mouse
vm_drag
Click-and-drag with 4 interpolated points.
mouse
vm_scroll
Wheel detents at cursor.
mouse
vm_cursor_position
Last-known (x, y).
keyboard
vm_type
Type ASCII text, Shift per char.
keyboard
vm_key
Chord: return, ctrl+alt+t, shift+f10 …
timing
vm_wait
Sleep N ms (clamped to 60 s).
ocr
vm_find_text
Tesseract → bounding box + center.
ocr
vm_click_text
OCR + click center. No coord-guessing.
ocr
vm_wait_for_text
Poll until text appears.
lifecycle
vm_list
All defined VMs and their state.
lifecycle
vm_info
State, vcpu, memory, VNC endpoint.
lifecycle
vm_start
Boot a VM that's shut off.
lifecycle
vm_shutdown
ACPI shutdown · graceful.
lifecycle
vm_force_off
Hard power off when stuck.
lifecycle
vm_reboot
Reboot in place.
snapshot
vm_snapshot_create
qcow2 snapshot · disk + memory.
snapshot
vm_snapshot_restore
Revert to snapshot in ~2 s.
snapshot
vm_snapshot_list
All snapshots for a VM.
snapshot
vm_snapshot_delete
Remove a named snapshot.
pool
vm_clone
Linked-clone from golden base.
pool
vm_destroy_clone
Drop a clone + its overlay.
pool
vm_pool_acquire
Get a warm clone in ~200 ms.
pool
vm_pool_release
Return a clone to the pool.
pool
vm_pool_status
Available / busy counts.
pool
vm_pool_shutdown
Tear down the pool.
scale

From one VM to a distributed mesh.

The architecture grows in 4 tiers. Shipped today: tier 0 (single body) + tier 1 (linked-clone pool). The rest is queued.

0shipped

Single local VM

One agent, one libvirt-managed VM, virsh subprocess. 29 MCP tools, ~30 s boot, golden-snapshot revert in ~2 s. Available today.

v0.2
1shipped

Pool · linked clones

One golden base image (qcow2 RO) + N copy-on-write overlays. aido-vmd daemon holds N VMs warm, allocates in ~200 ms. ~100 parallel agents on 32 GB RAM. Shipped v0.3.

v0.3
2queued

Multi-host · gRPC + catalog

Distributed VM hosts, gRPC API, etcd/consul catalog, snapshots in S3/MinIO, libvirt live-migration. The "compute pool" for agent fleets.

~3 weeks
3R&D

CRIU snapshots · WebRTC stream

Process-level checkpoint/restore (CRIU) for sub-second state transitions. WebRTC display + audio with native cursor at < 50 ms latency for multimodal LLMs that consume video natively.

~3 months
quickstart

From zero to a live agent body.

Linux, libvirt, qemu · that's it. No build deps beyond a Rust toolchain. Tested on Debian 14 + Alpine 3.21.

# 1. Build cargo build -p aido-vm --release # 2. Provision a tiny Alpine test VM (~50 MB, ~3 min) bash scripts/aido-vm-setup.sh # 3. Or a full Debian + Xorg + Firefox VM (~5 min) bash scripts/aido-vm-firefox-setup.sh # 4. Drive via the friendly CLI bash scripts/aido-vm vms # list VMs bash scripts/aido-vm shot # screenshot + xdg-open bash scripts/aido-vm click 460 590 # mouse click bash scripts/aido-vm type "hello" # keyboard input bash scripts/aido-vm click-text "login" # OCR-based click # 5. Browser-based live view with cursor overlay bash scripts/aido-vm-watch.sh # http://localhost:7841/ # 6. Mission Control (pool dashboard, live thumbnails) bash scripts/aido-vm-control-start.sh # http://localhost:7901/