vagrant-skill

Disposable VMs for safe testing — an Agent Skills standard skill

| | | |---|---| | Repo | daax-dev/vagrant-skill | | Stack | Vagrant, Shell, Ubuntu 24.04 | | Skill | Agent Skills standard | | Compatible | Claude Code, Claude.ai, OpenClaw, Cursor, Gemini CLI, and 30+ agents | | License | Apache 2.0 |

What It Does

Provides disposable, fully-provisioned Ubuntu 24.04 VMs for safe experimentation:

• Full sudo access — agents and humans can do anything without risk to the host
• Pre-installed tooling — Go 1.24, Docker, mage, build-essential, network tools
• Nested KVM — hardware virtualization passthrough (Linux with libvirt)
• Configurable — sync any project, adjust CPU/RAM/Go version via env vars
• Destroy and recreate — VMs are ephemeral, nothing persists unless you want it
• Cross-platform — tested on Mac (Parallels), Linux (libvirt), with VirtualBox as fallback

Quick Start

# Start VM (no project sync)
vagrant up

# Start VM with your project synced into /project
PROJECT_SRC=~/myproject vagrant up

# Run commands inside (agent workflow — no interactive SSH needed)
vagrant ssh -c "sudo apt-get install -y something"
vagrant ssh -c "cd /project && make test"

# Sync code changes from host
vagrant rsync

# Destroy and start fresh
vagrant destroy -f

Examples

Three self-contained examples, one per platform. Each has a Vagrantfile, a scripts/provision.sh, and a test/e2e.bats suite. Run them the same way:

vagrant up
bats test/e2e.bats
vagrant destroy -f

Linux — nginx-hardened (examples/nginx-hardened/)

Deploys nginx with a hardened iptables firewall (INPUT DROP by default, allow SSH + HTTP only). 16 bats tests.

Why it needs a VM: iptables -F INPUT + -P INPUT DROP on the host locks you out of your own SSH session. Provider: libvirt.

cd examples/nginx-hardened
vagrant up
bats test/e2e.bats
vagrant destroy -f

Ask the LLM:

/vagrant Run the nginx-hardened example in examples/nginx-hardened/, show me the full bats output, then destroy the VM.

Mac — docker-compose (examples/mac-docker-compose/)

Runs a Docker Compose stack: nginx on port 80 proxying a Python JSON API on port 8000 (internal only). 14 bats tests.

Why it needs a VM: Docker Desktop requires a commercial license and proxies port bindings through a hyperkit shim. Docker CE in a Parallels VM has no restrictions. Provider: Parallels (Apple Silicon).

cd examples/mac-docker-compose
vagrant up --provider=parallels
bats test/e2e.bats
vagrant destroy -f

Ask the LLM:

/vagrant Run the mac-docker-compose example in examples/mac-docker-compose/, show me the bats results proving the stack is up, then tear it down.

Windows — systemd-service (examples/windows-systemd-service/)

Deploys a Python HTTP server as a real systemd unit file, running as a dedicated demo system user. 20 bats tests including service restart after SIGKILL.

Why it needs a VM: WSL2 does not run real systemd — you can't test unit files without a proper Linux VM. Provider: VirtualBox.

WSL2 setup before vagrant up:

export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"

cd examples/windows-systemd-service
vagrant up --provider=virtualbox
bats test/e2e.bats
vagrant destroy -f

Ask the LLM:

/vagrant Run the windows-systemd-service example in examples/windows-systemd-service/, show me the bats output and journald logs, then destroy the VM.

Configuration

| Variable | Default | Purpose | |----------|---------|---------| | PROJECT_SRC | auto-detect | Host directory to sync into VM at /project | | VM_CPUS | 4 | Number of vCPUs | | VM_MEMORY | 4096 | RAM in MB | | VM_NAME | vagrant-skill-dev | VM hostname | | GO_VERSION | 1.24.3 | Go version to install |

PROJECT_SRC=~/myapp VM_CPUS=8 VM_MEMORY=8192 vagrant up

Install as a Skill

Note: The skill name is vagrant. When installing, clone into a directory named vagrant (not vagrant-skill) so the directory name matches the skill name per the Agent Skills spec.

Claude Code

# Global (available in all projects)
git clone [email protected]:daax-dev/vagrant-skill.git ~/.claude/skills/vagrant

# Per-project
git clone [email protected]:daax-dev/vagrant-skill.git .claude/skills/vagrant

Then use /vagrant in Claude Code.

ClawHub

npx clawhub@latest install vagrant

Other Agent Skills-Compatible Agents

Any agent that supports the Agent Skills standard can use this skill. Install into the agent's skill directory with the name vagrant:

git clone [email protected]:daax-dev/vagrant-skill.git <agent-skills-dir>/vagrant

Platform Setup

Mac (Apple Silicon — M1/M2/M3/M4) — Recommended: Parallels

VirtualBox on Apple Silicon is experimental and unreliable. Use Parallels.

# 1. Install Parallels Desktop (requires license)
#    Download from https://www.parallels.com/products/desktop/

# 2. Install Vagrant
brew install --cask vagrant

# 3. Install the Parallels provider plugin
vagrant plugin install vagrant-parallels

# 4. Clone and start
git clone [email protected]:daax-dev/vagrant-skill.git vagrant
cd vagrant
vagrant up --provider=parallels

Verified working: macOS 26.3, Apple Silicon (arm64), Parallels Desktop, Vagrant 2.4.9, bento/ubuntu-24.04 arm64 box. Setup provisions Go 1.24.3 (arm64), Docker, mage. 11/11 checks pass.

KVM note: Nested KVM is not available on Mac (no /dev/kvm). The VM still provides Docker, Go, mage, and full sudo. If you need nested KVM (e.g., for Firecracker microVM testing), use a Linux host.

Mac (Intel) — VirtualBox

brew install --cask virtualbox
brew install --cask vagrant
git clone [email protected]:daax-dev/vagrant-skill.git vagrant
cd vagrant
vagrant up --provider=virtualbox

Linux — Recommended: libvirt/KVM

This is the most capable setup — includes nested KVM for microVM testing.

sudo apt-get install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils
sudo apt-get install -y vagrant
vagrant plugin install vagrant-libvirt
git clone [email protected]:daax-dev/vagrant-skill.git vagrant
cd vagrant
vagrant up --provider=libvirt

Nested KVM is automatically enabled (cpu_mode: host-passthrough). Verify:

test -e /dev/kvm && echo "KVM OK"
vagrant ssh -c "test -e /dev/kvm && echo 'Nested KVM OK'"

Windows (WSL2) — VirtualBox

# Install VirtualBox on Windows (not inside WSL2)
# Inside WSL2:
sudo apt-get install -y vagrant
export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
git clone [email protected]:daax-dev/vagrant-skill.git vagrant
cd vagrant
vagrant up --provider=virtualbox

Using as a Consumer

Projects that depend on vagrant-skill for dev environments:

# From vagrant-skill directory, point to your project
PROJECT_SRC=~/path/to/your-project vagrant up

# Then run project-specific setup inside the VM
vagrant ssh -c "sudo /project/scripts/my-setup.sh"

What's In The VM

| Tool | Version | Notes | |------|---------|-------| | Ubuntu | 24.04 LTS | bento/ubuntu-24.04 box | | Go | 1.24.3 | arm64 or amd64 auto-detected | | Docker | Latest CE | Daemon running, vagrant user in docker group | | mage | Latest | Go build tool | | build-essential | System | gcc, make, etc. | | Network tools | System | iptables, dnsmasq, iproute2, dig, net-tools | | KVM tools | System | Only on Linux with nested KVM | | sqlite3 | System | With libsqlite3-dev | | jq, curl, git | System | Standard utilities |

Testing

# Lint (shellcheck + ruby syntax)
make lint

# Unit tests (58 bats tests)
make test

# Full integration (spins up VM, provisions, verifies, destroys)
make test-integration

# All
make test-all

Project Structure

vagrant-skill/
├── Vagrantfile                    # Multi-provider (Parallels, libvirt, VirtualBox)
├── SKILL.md                       # Agent Skills standard skill definition
├── scripts/
│   ├── setup.sh                   # Provisioner: system deps, Docker, Go, mage, KVM
│   └── verify.sh                  # Validation suite (11 checks)
├── examples/
│   ├── nginx-hardened/            # Linux/libvirt:    nginx + iptables firewall (16 tests)
│   ├── mac-docker-compose/        # Mac/Parallels:    Docker Compose stack (14 tests)
│   └── windows-systemd-service/   # Windows/VirtualBox: systemd unit file (20 tests)
│       (each has Vagrantfile, scripts/provision.sh, test/e2e.bats)
├── references/                    # Progressive disclosure
│   ├── platform-setup.md          # Detailed provider installation
│   └── vm-contents.md             # VM filesystem and software reference
├── docs/                          # Project documentation
├── test/                          # bats-core tests (unit + integration)
├── Makefile                       # lint, test, test-integration, up, destroy
├── README.md
├── CLAUDE.md
└── LICENSE                        # Apache 2.0

License

Apache 2.0