Skip to main content

​
Installation

The smolvm CLI is installed automatically when you install the SmolVM package: 
pip install smolvm
For dashboard functionality, install with the dashboard extra: 
pip install 'smolvm[dashboard]'

​
Basic Usage

The smolvm command provides several subcommands for managing VMs and system diagnostics: 
smolvm <command> [options]

​
Available Commands

doctor

Run host diagnostics for your selected backend

cleanup

Clean stale SmolVM resources and VMs

env

Manage environment variables on running VMs

ui

Start the SmolVM dashboard UI server

​
Getting Help

Display the main help message: 
smolvm --help
Get help for a specific command: 
smolvm doctor --help
smolvm cleanup --help
smolvm env --help

​
Exit Codes

SmolVM CLI commands follow standard Unix exit code conventions:
  • 0: Success
  • 1: General failure or error
  • 2: Invalid usage or missing required arguments
  • 130: Interrupted by user (Ctrl+C)

​
CLI Scripts

SmolVM provides two CLI entry points:
​
smolvm
string
Main CLI with all subcommands (doctor, cleanup, env, ui)
​
smolvm-cleanup
string
Standalone cleanup utility for convenience

​
Common Workflows

​
First-Time Setup Validation

After installing SmolVM, verify your system is properly configured: 
smolvm doctor
If you encounter failures, run the system setup script: 
sudo ./scripts/system-setup.sh --configure-runtime

​
VM Resource Management

Clean up stale or auto-created VMs: 
# Preview what will be deleted
smolvm cleanup --dry-run

# Clean auto-created VMs (vm-* prefix)
smolvm cleanup

# Clean all VMs
smolvm cleanup --all

​
Environment Configuration

Set environment variables on a running VM: 
# Set multiple variables
smolvm env set my-vm API_KEY=secret DATABASE_URL=postgres://...

# List variables (values masked by default)
smolvm env list my-vm

# Show actual values
smolvm env list my-vm --show-values

# Remove variables
smolvm env unset my-vm API_KEY DATABASE_URL

​
Dashboard UI

Launch the web-based dashboard: 
# Start on default port 8080
smolvm ui

# Custom host and port
smolvm ui --host 0.0.0.0 --port 3000

​
Configuration

The CLI respects the following environment variables:
​
SMOLVM_DASHBOARD_ALLOW_BETA
boolean
Allow dashboard UI downloads from prerelease/beta tags (set by --allow-beta flag)
​
SMOLVM_DASHBOARD_URL
string
Dashboard URL (automatically set by the ui command)

​
SSH Configuration

Commands that interact with VMs (like env) use SSH. By default:
  • SSH User: root
  • SSH Key: ~/.smolvm/keys/id_ed25519
You can override these with command-line flags: 
smolvm env list my-vm --ssh-user admin --ssh-key ~/.ssh/custom_key
SmolVM automatically generates SSH keys during VM creation if they don’t exist.

​
Next Steps

Doctor Command

Learn about system diagnostics

Cleanup Command

Understand resource management

Environment Commands

Configure VM environments

Dashboard UI

Explore the web interface

Build docs developers (and LLMs) love

Get started for freeTalk to us