User Input

CODEBLOCK0

You MUST consider the user input before proceeding (if not empty).

Execution Instructions

This skill provides a disposable VM sandbox for safe development and testing. All privileged operations (sudo, iptables, Docker, systemd, KVM) happen inside the VM — the host is never modified.

You (the agent) should NEVER need host-level sudo. Instead, use this Vagrant workflow to get a fully provisioned, disposable VM where you have unrestricted root access.

Prerequisites

Before using this workflow, verify a provider is available:

CODEBLOCK1

See references/platform-setup.md for detailed provider installation.

Core Workflow

Step 1: Create a Vagrantfile in the User's Project

If the user's project does not already have a Vagrantfile, you MUST create a real, working one in their project directory. This is not a template or example — it must work end-to-end with vagrant up.

Requirements for the Vagrantfile you create:

• - Base box: INLINECODE2
• Sync the project root into the VM: INLINECODE3
• Include all three providers (Parallels, libvirt, VirtualBox) so it works on any platform
• Provision with the actual tools the project needs (inspect the project first — look for go.mod, package.json, requirements.txt, Makefile, Dockerfile, etc.)
• Use set -euo pipefail in provisioning scripts
• Make provisioning idempotent

Here is the base Vagrantfile — you MUST customize the provisioning section based on what the project actually uses:

CODEBLOCK2

You MUST customize the provisioning section. Read the project to determine what it needs:

• - go.mod → install Go
• INLINECODE11 → install Node.js
• INLINECODE12 / pyproject.toml → install Python
• INLINECODE14 → Docker is already included above
• Network testing → add INLINECODE15
• KVM/microVM testing → add INLINECODE16

Uncomment the relevant blocks and add any other tooling. Do NOT leave placeholder comments in the final Vagrantfile — produce a clean, working file.

Then add .vagrant/ to the user's .gitignore if not already present:

CODEBLOCK3

The Vagrantfile itself should be committed — it's reusable project infrastructure.

If the user already has a Vagrantfile, use it as-is unless they ask to modify it.

Step 2: Start the VM

CODEBLOCK4

This boots the VM with the user's project synced at /project inside the VM.

Step 3: Run Commands Inside the VM

All commands use vagrant ssh -c from the host. No interactive SSH needed.

CODEBLOCK5

Step 4: Iterate on Code Changes

When you modify source on the host:

CODEBLOCK6

Step 5: Tear Down

CODEBLOCK7

Testing Patterns

Pattern: Build-Test-Fix Loop

CODEBLOCK8

Pattern: Docker-in-VM

CODEBLOCK9

Pattern: Network/Firewall Testing

CODEBLOCK10

Pattern: bats End-to-End Tests

Run a bats-core test suite against a live VM as proof that the system under test works. The VM must be up before running bats.

CODEBLOCK11

Capture output to show the user:

CODEBLOCK12

bats exits non-zero on any failure — treat that as a test run failure.

Pattern: Full Reprovision (Nuclear Option)

CODEBLOCK13

Configuration

Environment variables to customize the VM (set before vagrant up):

Example:
CODEBLOCK14

See references/vm-contents.md for full details on VM filesystem layout and installed software.

Safety Guarantees

• - No host sudo required — all privileged operations are inside the VM
• Fully disposable — vagrant destroy -f removes everything
• Idempotent provisioning — vagrant provision is safe to re-run
• Isolated networking — VM has its own network stack
• Source is rsynced — VM gets a copy; your host repo is never modified by the VM
• No persistent state — destroying the VM removes all data
• Vagrantfile is committed — reusable across sessions; .vagrant/ is gitignored

Examples

Example 1: Test iptables firewall rules without touching host network

User says: "I need to test some firewall rules before deploying to production"

Actions:

1. 1. Create Vagrantfile with iptables dnsmasq dnsutils iproute2 net-tools provisioned
2. INLINECODE29
3. INLINECODE30
4. INLINECODE31
5. INLINECODE32 — verify rules look right
6. INLINECODE33 — export if good
7. INLINECODE34 to get rules file back, or vagrant destroy -f to scrap

Result: Firewall rules iterated safely. Host network never touched. Rules exportable.

Example 2: Test systemd service configuration

User says: "I need to test this systemd unit file before deploying"

Actions:

1. 1. Create Vagrantfile with the project synced
2. INLINECODE36
3. INLINECODE37
4. INLINECODE38
5. INLINECODE39 — check it works
6. INLINECODE40 — check logs
7. INLINECODE41 — clean slate

Result: Service tested with real systemd, real journald. No risk to host init system.

Example 3: Docker daemon configuration and privileged port binding

User says: "I need to test a Docker compose setup that binds port 80"

Actions:

1. 1. Create Vagrantfile with Docker CE provisioned
2. INLINECODE42
3. INLINECODE43
4. INLINECODE44 — test from inside VM
5. INLINECODE45 — check output
6. INLINECODE46 — cleanup
7. INLINECODE47

Result: Full Docker compose stack running with privileged ports — impossible without sudo on the host.

Example 4: Run the built-in e2e examples

Three working examples live under examples/ in this skill's directory. All follow the same pattern — boot, test, tear down:

CODEBLOCK15

examples/nginx-hardened/ — Linux / libvirt (16 tests)

Deploys nginx + hardened iptables (INPUT DROP, allow SSH + HTTP only).
Why VM: iptables -F INPUT; iptables -P INPUT DROP on the host locks you out.

CODEBLOCK16

examples/mac-docker-compose/ — Mac Apple Silicon / Parallels (14 tests)

Runs a Docker Compose stack: nginx on port 80 proxying a Python JSON API.
Why VM: Docker Desktop requires a commercial license; Docker CE in a VM has none of its restrictions.

CODEBLOCK17

examples/windows-systemd-service/ — Windows WSL2 / VirtualBox (20 tests)

Deploys a Python HTTP server as a real systemd unit, running as a dedicated system user.
Why VM: WSL2 does not run real systemd — unit files cannot be tested without a real Linux init.

WSL2 pre-flight:
CODEBLOCK18

CODEBLOCK19

Troubleshooting

VM Won't Boot

Error: vagrant up hangs or times out
Cause: Provider not installed or configured correctly
Solution:

1. 1. Check provider is installed: INLINECODE54
2. Debug boot: INLINECODE55
3. Try explicit provider: INLINECODE56

Source Not Synced

Error: /project directory is empty or missing inside VM
Cause: rsync failed or synced_folder misconfigured
Solution:

1. 1. Re-sync: INLINECODE58
2. Check Vagrantfile has INLINECODE59

Provider Mismatch

Error: vagrant up uses wrong provider
Cause: Multiple providers installed, Vagrant auto-selects
Solution:

1. 1. Check what's running: INLINECODE61
2. Force provider: INLINECODE62

KVM Not Available Inside VM

Error: /dev/kvm missing inside the VM
Cause: Host doesn't support nested virtualization or provider not configured
Solution:

1. 1. Ensure host has KVM: test -e /dev/kvm on host
2. Use libvirt provider with INLINECODE65
3. Mac: nested KVM is not available — use a Linux host for KVM workloads