"Hatch your agents. Let them fly." 🐣💾

![Release](https://github.com/Josepavese/nido/releases) ![License](LICENSE) ![Go Report Card](https://goreportcard.com/report/github.com/Josepavese/nido)

Nido is the retro-futuristic nest for your AI agents. It spawns real Virtual Machines in milliseconds, giving your autonomous code a safe place to hatch, grow, and execute.

Containers are cages. Nido is a habitat. 🪺

Built on QEMU and fueled by 80s nostalgia, Nido feels like a game console for DevOps. It provides a full, unconstrained OS for your agents to explore, break, and rebuild.

---

🕹️ The Game Loop: Spawn -> Execute -> Destroy

!The Lifecycle

INSERT COIN (Spawn): An agent needs a body. Nido "hatches" a VM from a cached genetic sequence (Image) instantly using Linked Clones technology.
PLAY (Execute): The VM is alive. The agent connects via SSH (Neural Link) and has full root access. No shared kernels. No rules.
GAME OVER (Destroy): The mission is complete. The VM is vaporized. The nest remains pristine for the next player.

---

⚡ Loading... (Installation)

SYSTEM REQUIREMENTS: Linux, macOS, Android (Termux), or Windows (WSL2/PowerShell). QEMU is required to run VMs; the quick installers check for it and offer to install it where supported. On Windows, the installer can also register/install winget and enable Windows Hypervisor Platform for WHPX acceleration.

WINDOWS STATUS: Windows host support is now smoke-tested on a real Windows VM: online installer parsing, nido doctor, catalog/blueprint listing, and basic VM lifecycle passed. Treat it as usable for core workflows, but still young compared with Linux/macOS; it needs heavier long-running and workload-specific testing.

💾 Quick Install (Web)

Run this command in your terminal. Do not turn off the console while saving.

Linux & macOS:

{ curl -fsSL https://github.com/Josepavese/nido/releases/latest/download/install.sh || curl -fsSL https://raw.githubusercontent.com/Josepavese/nido/main/installers/quick-install.sh; } | bash
# Restart your terminal or source your config to initialize the matrix
source ~/.bashrc  # or ~/.zshrc, power up the path
nido version         # Check checksum

Windows (PowerShell):

try { irm https://github.com/Josepavese/nido/releases/latest/download/install.ps1 | iex } catch { irm https://raw.githubusercontent.com/Josepavese/nido/main/installers/quick-install.ps1 | iex }
# Restart your terminal to initialize the matrix
nido version

ARM Linux SBCs:

Run this inside your favorite ARM-based Linux distro (Raspberry Pi, Pine64, etc). Android/Termux users should prefer the source installer when Android-specific packages are needed.

{ curl -fsSL https://github.com/Josepavese/nido/releases/latest/download/install.sh || curl -fsSL https://raw.githubusercontent.com/Josepavese/nido/main/installers/quick-install.sh; } | bash
# Reload your config
source ~/.bashrc
nido version

🪄 Cheat Codes (Auto-Complete)

Tab-completion is enabled by default. If it's missing, equip it manually:

# Add to ~/.bashrc or ~/.zshrc
source <(nido completion bash)  # or zsh / fish / powershell

---

🦄 Select Your Flavour

!Select Flavour

Nido supports a wide roster of "fighters" (Cloud Images). Ubuntu, Debian, Alpine, Arch, choose your pixelated champion.

Windows Blueprints

Windows images are available as buildable blueprints because Microsoft distributes installer media rather than ready-to-run qcow2 cloud images. The current official-name entries are:

windows-11-eval - Windows 11 Enterprise Evaluation
windows-11-iot-ltsc-eval - Windows 11 IoT Enterprise LTSC 2024 Evaluation
windows-server-2022-core-eval - Windows Server 2022 Evaluation (Server Core)

nido blueprint list
nido blueprint build windows-11-eval
nido spawn my-win --image windows-11-eval --gui

The first boot may continue Windows OOBE/post-install work after the blueprint build reports ready. Use --gui for that first boot so the setup state is visible.

🎮 Real World Example (Combo Move)

Let's hatch a Ubuntu 24.04 bird named agent-01, attach a graphical interface (GUI), and log in immediately.

# 1. DOWNLOAD ROM (Pull Image)
nido images pull ubuntu:24.04

# 2. START GAME (Spawn VM with GUI and custom resources)
nido spawn agent-01 --image ubuntu:24.04 --gui --memory 4096 --cpus 4

# 3. LINK CABLE (SSH Connection)
nido ssh agent-01

Result: A fresh VM boots in <2 seconds. A VNC window opens. You are root.

---

🦾 Neural Interface (For AI Agents)

Nido is designed to be driven by Large Language Models (Claude, GPT-4, Gemini).

🤖 Model Context Protocol (MCP)

Nido speaks native MCP. The server now exposes a compact agent-facing surface: a few high-power tools (nido_vm, nido_template, nido_image, nido_blueprint, nido_system) plus read-only resources like nido://fleet/vms, nido://catalog/blueprints, and nido://system/config. This reduces tool-selection ambiguity, lowers token overhead, and makes agent planning simpler than a flood of one-action tools.

nido register  # Generates the config for your AI client
nido mcp --help  # Human-readable MCP guide
nido mcp-help    # Machine-readable MCP guide for agents

🧩 Agent Skill

Nido also ships an optional Codex-compatible skill for developers who want agents to use Nido as a standard VM test and isolation layer.

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R extras/skills/nido-vm-testing "${CODEX_HOME:-$HOME/.codex}/skills/"

The skill teaches agents how to spawn disposable VMs, provision prerequisites with --user-data, upload software under test, parse dynamic ports, run tests, remove the VM, and speed repeated runs with templates. See docs/agent-skills.md.

🧠 JSON Mode

Every command supports --json. Perfect for scripts and robot eyes.

nido ls --json
# Output: {"vms": [{"name": "agent-01", "state": "running", "ip": "10.0.2.15"}]}

---

🕹️ Control Deck (Command List)

Here is the full move list for the Nido console.

🐣 Life Cycle (The Game Loop)

🔍 Observability (HUD)

🔌 Connectivity (Link Cable)

🧬 Genetic Engineering (Images & Templates)

⚙️ System (Options Menu)

---

🧬 Killer Feature: Linked Clones

Why download 2GB every time? Nido downloads the generic "Common ROM" (Base Image) once.

Every VM you spawn is just a diff layer (mutation) on top of that ROM.

Base Image: Read-Only. Safe.
VM Disk: Read-Write. Ephemeral.

Result: Spawn 100 VMs, use disk space for 1. 🚀

---

🤝 Contributing

Insert Coin to Join.

Fork the repo.
go run ./cmd/nido gui to test the Arcade UI.
Run go run ./cmd/nido-validator to insure your code withstands the pressure.
Submit a PR.
High Scores are recorded in AUTHORS.

📜 License

MIT License. Free as in "Free Play".

---

Made with 💜 and ☕ by digital artisans. EST. 2025 • "The Grid. A digital frontier."

Nido — Fast, Simple VM Sandboxes for AI Agents (Temporary & Persistent)