CLI overview - Celesto AI

The SmolVM CLI lets you manage sandboxes, start browser sessions, and inspect the runtime from your terminal. Use it when you want to work with SmolVM outside of Python code.

Installation

Install SmolVM via pip:

pip install smolvm

For dashboard support, install with the dashboard extra:

pip install 'smolvm[dashboard]'

Available commands

Command	Description
`smolvm setup`	One-time host setup (installs runtime dependencies)
`smolvm create`	Create an SSH-ready VM (name is optional)
`smolvm list`	List VMs and their current status
`smolvm stop`	Stop a running VM and release its resources
`smolvm ssh`	SSH into an existing VM (auto-starts if stopped)
`smolvm browser`	Manage disposable browser sessions
`smolvm snapshot`	Create, restore, list, and delete VM snapshots
`smolvm cleanup`	Clean stale SmolVM resources and VMs
`smolvm doctor`	Run host diagnostics for the selected backend
`smolvm env`	Manage environment variables on a running VM
`smolvm windows`	Windows-guest helpers (build a Windows qcow2 from an ISO)
`smolvm ui`	Start the SmolVM dashboard UI server

Snapshot commands

The smolvm snapshot command has its own subcommands for managing Firecracker VM snapshots:

Command	Description
`smolvm snapshot create`	Create a full snapshot from a running or paused VM
`smolvm snapshot restore`	Restore a snapshot back into its original VM
`smolvm snapshot list`	List all snapshots
`smolvm snapshot delete`	Delete a snapshot and its files

Create a snapshot and restore it later:

smolvm snapshot create my-vm --snapshot-id my-checkpoint
smolvm snapshot restore my-checkpoint --resume

Browser commands

The smolvm browser command has its own subcommands for managing disposable browser sessions:

Command	Description
`smolvm browser start`	Create and start a browser session
`smolvm browser list`	List browser sessions
`smolvm browser stop`	Stop and delete a browser session
`smolvm browser open`	Open a live session in your default browser
`smolvm browser logs`	Print browser session logs

Start a disposable browser session with live view:

smolvm browser start --live --json

The JSON response includes the session_id plus local browser URLs. Use the session ID with other browser commands:

smolvm browser list
smolvm browser open <session_id>
smolvm browser stop <session_id>

Windows commands

The smolvm windows command bundles helpers for Windows guests:

Command	Description
`smolvm windows build-image`	Build a Windows 11 qcow2 from a Windows ISO via unattended install

Build a Windows image once, then boot as many sandboxes as you want from it:

smolvm windows build-image \
  --iso ./Win11.iso \
  --virtio-win-iso ./virtio-win.iso \
  --output ~/.smolvm/images/win11.qcow2

See smolvm windows for the full reference.

Getting help

Display help for the main command:

smolvm --help

Display help for a specific subcommand:

smolvm create --help
smolvm browser start --help

Script aliases

smolvm-cleanup: Equivalent to smolvm cleanup (standalone cleanup command)

Next steps

List VMs

View running VMs and their status

Create a VM

Spin up an SSH-ready VM

SSH into a VM

Connect to a VM via SSH

Cleanup

Clean up stale VMs and resources

Doctor

Diagnose system requirements

Environment

Manage VM environment variables

Windows images

Build a Windows qcow2 from an ISO

Snapshots

Save and restore VM state

Dashboard UI

Launch the dashboard interface

Documentation Index

​Installation

​Available commands

​Snapshot commands

​Browser commands

​Windows commands

​Getting help

​Script aliases

​Next steps