Nido

Real virtual machines for AI agents. One local engine, three ways to drive it: CLI, TUI and MCP.

Give an agent a machine it can provision, use and delete. Nido runs QEMU locally, clones cached images with copy-on-write disks, and exposes the same VM lifecycle to your terminal and your MCP client. Each VM has its own guest kernel.

Hatch your agents. Let them fly. Retro shell, practical machinery.

Get started · Connect an agent · Documentation · Wiki

Why Nido?

Related MCP server: proxmox-mcp

Press start

QEMU is required to run VMs. Nido supports Linux, macOS and Windows hosts; hardware acceleration depends on what the host actually exposes. Start with nido doctor. See installation and host requirements.

Install

Linux / macOS

curl -fsSL https://github.com/Josepavese/nido/releases/latest/download/install.sh | bash

Windows PowerShell

irm https://github.com/Josepavese/nido/releases/latest/download/install.ps1 | iex

Open a new terminal, then check nido version and nido doctor. The quick installers check prerequisites and offer QEMU setup where supported.

Prefer a package manager?

brew install Josepavese/nido/nido       # macOS / Linux
npm install -g nido-mcp                # verified binary launcher
go install github.com/Josepavese/nido/v4/cmd/nido@latest

scoop bucket add nido https://github.com/Josepavese/scoop-nido
scoop install nido

All install options · Distribution channel status

Hatch your first VM

nido images update
nido images info ubuntu:lts
nido images pull ubuntu:lts
nido spawn agent-lab --image ubuntu:lts --memory 2048 --cpus 2
nido info agent-lab --json

# Once the guest has finished booting and SSH is ready:
nido ssh agent-lab

The first pull downloads the base image. Later VMs can reuse it. ubuntu:lts follows the catalog's supported LTS selection; use a numbered tag from nido images list when you need a specific OS release. Guest boot and cloud-init take additional time; creating the overlay is only one part of startup.

When you have saved the work you need, shut down inside the guest and remove only your disposable VM:

nido ssh agent-lab sudo poweroff
# After shutdown, confirm its state:
nido info agent-lab
nido delete agent-lab

nido stop terminates the managed QEMU process and waits for exit. Use guest poweroff for a clean OS shutdown. VM data persists until you delete it.

Provisioning, ports, templates and cleanup

Connect your agent

Nido's MCP server runs locally over stdio. No separate service is required. Use an installed binary:

{
  "mcpServers": {
    "nido": {
      "command": "nido",
      "args": ["mcp"]
    }
  }
}

Use the absolute executable path if your client does not inherit your terminal's PATH. nido register prints a registration block; your client owns where it is saved. Clients that launch npm packages can instead use command: "npx" with args: ["-y", "nido-mcp", "mcp"].

Read-only resources include nido://fleet/vms, nido://catalog/images and nido://system/config. Use nido mcp-help for the machine-readable tool/action guide, or nido mcp --help in your terminal.

An example task for your agent:

Create a disposable Ubuntu LTS VM named test-lab, provision the dependencies, run my tests and save their output. Delete only that VM when finished. Preserve other VMs and shared images.

MCP grants access to local VM and installation operations, including destructive ones. Connect clients you trust. MCP guide · Optional VM-testing skill

One base. Separate machines.

With linked clones enabled, the cached base stays shared while each VM records its own disk changes. Space usage grows with those writes, logs and templates; it is not constant as you add VMs. Nido checks backing-image dependencies before cache removal. Keep bases in place while dependent VM disks exist.

VMs provide a separate guest kernel, but host mounts, forwarded ports and PCI passthrough deliberately cross that boundary. Nido is not a complete security policy for arbitrary untrusted workloads. See operations and isolation.

Pick your starting point

• Cloud image: pull from the catalog and provision through cloud-init. Ubuntu, Debian, Alpine, Kali, CirrOS and openSUSE discovery follows the policies in registry/sources.yaml. Catalog and integrity

• Template: save a prepared VM disk and reuse it for repeated tasks. Template workflow

• Blueprint: build an image from a recipe and installer media, including Windows evaluation editions. Windows guide

The scheduled catalog job discovers new supported upstream releases. Refresh your local copy with nido images update; it does not update an existing guest OS.

Prefer hands-on control? Run nido gui for the Fleet, Hatchery, Registry and System views. Use --gui on spawn/start when you want the VM's display; that flag and the terminal dashboard are separate features.

Go further

Documentation index · Changelog · Issues · MIT license