Nido - VM Manager for AI Agents

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?

You want to...	Nido gives you...
Test code away from your host	Disposable QEMU VMs with SSH access and cloud-init provisioning
Let an agent manage its own environment	A built-in stdio MCP server with compact tools, read-only resources and opt-in event subscriptions
Reuse an expensive setup	Templates and QCOW2 linked clones, with one shared base and a writable disk per VM
Switch between automation and hands-on work	Structured CLI JSON, shell completion and an interactive terminal dashboard
Keep multiple dashboards and agents in sync	Shared local events, live TUI updates and selective MCP notifications
Choose the right starting point	An automatically refreshed cloud-image catalog, local templates and buildable blueprints

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? npm works on Linux, macOS and Windows:

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

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

Container (Docker/Podman, bundles QEMU; needs a KVM-capable host):

docker run -i --rm --device /dev/kvm \
  --group-add "$(stat -c %g /dev/kvm)" \
  -v nido-home:/home/nido/.nido \
  ghcr.io/josepavese/nido mcp

Images are rebuilt on every release at ghcr.io/josepavese/nido (:{version}, :{minor}, :latest) and speak MCP on stdio; pass --group-add so the non-root user can open /dev/kvm.

WinGet: Josepavese.Nido is awaiting Microsoft review. See availability and commands.

For MCP clients, use npx -y nido-mcp mcp, discover io.github.Josepavese/nido in the Official MCP Registry, browse Glama, or import the MCPB bundle. MCP catalogs and client installation.

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

Watch core changes in another terminal with nido events or nido events --json. TUI sessions update from the shared stream; agents explicitly subscribe only to the resources they need. See event delivery and mute controls.

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"].

Tool	Responsibility
nido_vm	Create, inspect, configure, connect and remove VMs; manage forwarded ports
nido_image	Browse and refresh the catalog; pull and manage cached images
nido_template	Save and manage reusable disk templates
nido_blueprint	Inspect and build image recipes
nido_system	Diagnostics, configuration, accelerators and installation operations

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

Task	Guide
Provision a guest, forward ports, adjust resources, share files	Everyday workflows
Write scripts against Nido	CLI JSON contract
Install, upgrade or choose a package channel	Installers · Distribution
Change the terminal palette	Themes
Understand runtime and hardware boundaries	Architecture
Contribute or validate a change	Contributing · Testing

Documentation index · Changelog · Issues · MIT license