How to use the smolvm Teardown agent skill: clean up VMs and files

What the teardown skill makes the agent do

Once installed, the agent knows how to stop every smolvm machine a session started, find and remove leftover smolvm files and processes, and run checks that prove nothing was left behind. It also explains how to uninstall smolvm and reclaim disk space.

The skill only deletes machines that a script recorded under its own name prefix (smolskill-). Machines you or another session created by hand are left alone unless you ask the agent to delete them, and then it confirms each one first.

• Stops machines a session started and reports any leftover VM processes
• Checks for smolvm state that remains after a run, a crash or an interrupted Ctrl-C
• Runs verification checks that report ok or FAIL for each item
• Explains how to prune unused layers and uninstall smolvm

Install the teardown skill

Download the ZIP for the teardown skill from this page. You can install it in one of two ways.

For Claude Code, unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder to make it available only in that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what is on your host before cleaning up

The first step the skill runs is a read-only preflight. It reports each smolvm state directory with its size, whether a bake cache exists, whether the launcher symlink and PATH block are present, and whether state can be relocated on your platform. It deletes nothing and starts no VM.

You can ask for this directly, for example: "Check what smolvm has left on this machine."

Stop machines and remove leftovers

The cleanup script first reports leftover VM processes. Running it with --reap kills every VM process under the current HOME, including any running machine you meant to keep, so read the report first and use --reap only when nothing there should keep running.

The script waits up to 20 seconds for ephemeral machines to retire, and it deletes only machines recorded in its state file. The state file lives under ${XDG_STATE_HOME:-$HOME/.local/state}/smolvm-skills/.

• Report only: run the script without flags
• Kill everything under this HOME: add --reap (use with care)
• Remove the state file once the list is empty: --purge

Prove the host is clean

Verification checks are scoped to the HOME they run under, and the audited_home= line shows which profile the result describes. Running them under a different, fresh HOME will report a clean host even when a VM is still running elsewhere, so do not rely on that result.

If you are testing under a scratch HOME while a real smolvm installation exists, pass --protected for each of the real installation's directories so the check confirms nothing was written there today. Each check prints ok or FAIL expected=... actual=..., and the script exits non-zero if any check failed.

• Pass --since with the time your test began, for example "2026-10-03 14:00"
• On macOS the protected directories are ~/Library/Application Support/smolvm and ~/Library/Caches/smolvm
• On Linux, run with XDG_DATA_HOME and XDG_CACHE_HOME unset, as the install was

Reclaim space or uninstall smolvm

To free disk space, prune unreferenced layers. Pruning a machine starts it if it is stopped. The --all flag also drops cached images, except for a machine created from an image. To uninstall smolvm, use the official uninstaller.

The uninstaller does not remove everything. On v1.18.2 on macOS it leaves ~/Library/Caches/smolvm-registry, and on v1.23.0 it leaves smolvm-image-archives beside the cache directory on both hosts. Remove those by hand after uninstalling.

• Prune a machine's unused layers with machine prune --name <NAME>
• Prune packs with pack prune
• Full file layout is in references/locations.md