How to use the Install and verify smolvm agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder of instructions and scripts that an AI agent such as Claude can load when a task matches the skill's description. This one is named install. Its job is narrow: get smolvm onto a fresh machine and prove that a virtual machine actually starts before any other work begins.

The skill's procedure has four steps: a read-only preflight check, an install from the published release, a boot test, and a cleanup. A version number alone is not treated as proof. Done means smolvm --version prints the release version and a throwaway VM has run one command and exited.

Install the skill in Claude

Download the ZIP for this skill from this page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload it there.

How do you trigger the skill with a natural request?

You do not need to name the skill. Ask for the kind of work it covers, and the agent matches the request against the skill's description. The description says it applies when you set smolvm up on a new machine, a CI runner or an agent's own environment, when a first boot fails with krun_start_enter -22, KVM_DENIED or "agent did not become ready", when you check whether a host meets smolvm's requirements, or when an install must be isolated and later removed.

• "Set up smolvm on this new Mac and confirm it can boot a VM."
• "My smolvm first boot fails with KVM_DENIED. Figure out why."
• "Check whether this Linux host meets smolvm's requirements."
• "Install smolvm into a scratch HOME so it doesn't touch my existing install."

What the skill runs, step by step

The preflight script reports the host as key=value lines and ends with result=ready, result=not_installed or result=blocked. A result of not_installed on a fresh host means the machine is fine and smolvm is simply missing. A result of blocked means you should read the note= lines before continuing.

The installer is run with curl. It writes under your HOME folder, adds a PATH line to your shell profile when needed, and the agent then checks smolvm --version. The boot test runs one ephemeral alpine VM and checks a marker the guest printed and that the guest kernel differs from the host's. The cleanup script waits up to 20 seconds, then confirms no machines remain.

• scripts/preflight.sh: read-only, starts no VM, writes no smolvm state
• scripts/verify-boot.sh: boots one alpine VM and checks the result; --image <ref> boots another image
• scripts/cleanup.sh: removes test machines; --reap kills leftover VM processes, so read the report first

Examples of what the skill does on a real host

On a Mac, the agent runs the preflight, installs smolvm, and boots the test VM. If Docker Hub returns TOOMANYREQUESTS, the skill tells you to name the same image from a mirror, such as mirror.gcr.io/library/alpine or public.ecr.aws/docker/library/alpine.

On a Linux host where your user cannot open /dev/kvm, the preflight reports accel_access=denied and stops. The skill does not widen access for you. The one privileged step, sudo usermod -aG kvm, is yours to run.

What the skill needs, and its safety notes

The host must be a Mac with arm64 chips or Linux on aarch64 or x86_64, with virtualization support: KVM on Linux and Hypervisor.framework on macOS. The skill also needs network access to smolmachines.com and a container image registry such as Docker Hub, plus bash, curl and standard shell tools.

The skill runs scripts and uses the network. It is designed to run as your own user. The installer needs no root and writes only under $HOME. Nothing in the packet escalates privilege. Group membership for /dev/kvm is the host's access boundary, so the skill reports the problem rather than changing it. The uninstaller leaves ~/.config/smolvm, which holds registry credentials, and your PATH line in place on purpose.

• Read scripts/preflight.sh and the other scripts before running them on a shared machine.
• Use a scratch HOME directory if you want the install to be removable without touching an existing one. This does not work on Windows.
• The skill is not for Windows. The source points to a separate Windows guide.

Tips for a smooth first boot

A default machine asks for 8192 MiB of memory, but the boot test uses 2048 MiB. A host can pass the test and still fail default-size machines with "agent did not become ready within 30 seconds". If your work uses the default size, boot one at that size too.

On macOS, a very deep install path can cause krun_start_enter returned: -22. Keep a scratch HOME shallow. Run the preflight again after the install if the first boot fails.

• Pin a version only to reproduce a recorded run. Otherwise the installer takes the newest release.
• Expect two notarization warnings on macOS installs; they are not a problem.
• Check each step's output against the binary, since flags and messages can change between releases.