Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Synopsis

smolvm cleanup [OPTIONS]

​
Description

The cleanup command removes stale or auto-created VMs and their associated resources. By default, it targets VMs with the vm- prefix and any VMs that have been reconciled as stale.
Running cleanup as root is recommended to ensure proper cleanup of TAP devices and nftables rules.

​
Options

​
--all
flag
default:"false"
Delete all VMs, not just stale or auto-created ones.
​
--prefix
string
default:"vm-"
Auto-VM prefix to clean. Only VMs starting with this prefix (or marked as stale) will be targeted.
​
--dry-run
flag
default:"false"
Print targets without deleting. Useful for previewing what would be cleaned up.
​
--force, -f
flag
default:"false"
Skip the confirmation prompt and delete the targeted VMs without asking. Required when running non-interactively (no TTY) or together with --json.

​
Confirmation prompt

Because cleanup permanently deletes VMs, the command lists the targeted IDs and asks you to confirm before doing anything: 
This will permanently delete 3 VM(s): vm-abc123, vm-test-001, vm-demo
This action cannot be undone.
Continue? [y/N]
Type y or yes to proceed. Anything else — including pressing Enter — aborts cleanly with exit code 0 and no VMs are deleted. Use --force to skip the prompt in scripts or CI. Without --force, smolvm cleanup refuses to run in two cases to avoid silently destroying data:
  • You passed --json (machine-readable output, no interactive prompt possible).
  • Standard input is not a TTY (for example, piped or redirected).
In either case, the command exits with 1 and prints an error telling you to add --force. --dry-run never deletes anything, so it does not prompt or require --force.

​
Examples

​
Clean auto-created VMs (default prefix)

Remove VMs with IDs starting with vm- and any stale VMs: 
smolvm cleanup
Example output: 
Reconciled stale VMs: vm-abc123
Targets (3):
  - vm-abc123
  - vm-test-001
  - vm-demo
This will permanently delete 3 VM(s): vm-abc123, vm-test-001, vm-demo
This action cannot be undone.
Continue? [y/N] y
Deleted: vm-abc123
Deleted: vm-test-001
Deleted: vm-demo
Cleanup complete.

​
Skip the prompt in scripts

Use --force (or -f) when you are running cleanup non-interactively and have already decided to delete everything: 
smolvm cleanup --force
Combine --force with --json for automation pipelines: 
smolvm cleanup --json --force

​
Preview cleanup targets

See what would be deleted without actually deleting: 
smolvm cleanup --dry-run
Example output: 
Reconciled stale VMs: vm-old
Targets (2):
  - vm-old
  - vm-test
Dry run complete. No changes made.

​
Clean VMs with custom prefix

Remove VMs starting with a custom prefix: 
smolvm cleanup --prefix agent-

​
Delete all VMs

This will delete all VMs, including manually created ones.
smolvm cleanup --all
Example output: 
Targets (5):
  - vm-auto-001
  - my-persistent-vm
  - dev-environment
  - test-vm
  - production-agent
Deleted: vm-auto-001
Deleted: my-persistent-vm
Deleted: dev-environment
Deleted: test-vm
Deleted: production-agent
Cleanup complete.

​
Cleanup Process

The cleanup command performs the following steps:
  1. Reconciliation: Identifies stale VMs (VMs with state entries but no running processes)
  2. Target Selection: Based on --all or --prefix, selects VMs to delete
  3. Resource Cleanup: For each target VM:
    • Stops the VM process (if running)
    • Removes TAP network devices
    • Cleans up nftables rules
    • Removes state database entries

​
Exit Codes

CodeDescription
0Success — all targets cleaned, or user declined at the confirmation prompt
1Partial failure, or refused to run unattended without --force (no TTY, or --json mode)

​
Standalone Command

The cleanup command is also available as a standalone script: 
smolvm-cleanup [OPTIONS]
This is functionally identical to smolvm cleanup.
Last modified on May 28, 2026