CLI overview

The SmolVM CLI lets you create and manage disposable computers from your terminal. Use it when you want to start a sandbox, open a shell, move files, expose a local port, or run the dashboard without writing Python code.

Install

Install the base CLI:

pip install smolvm

Install the dashboard and HTTP server dependencies:

pip install "smolvm[dashboard]"

Command groups

Command	What you can do
`smolvm sandbox`	Create, inspect, start, stop, pause, resume, connect to, and delete sandboxes; open macOS desktops with `sandbox desktop`
`smolvm sandbox exec`	Run one command inside a running sandbox from a script or agent
`smolvm sandbox logs`	Show a sandbox’s host boot and console log
`smolvm sandbox snapshot`	Save and restore sandbox state
`smolvm sandbox file`	Copy files into or out of a sandbox
`smolvm sandbox env`	Set, remove, and list sandbox environment variables
`smolvm sandbox port`	Share a sandbox port on `127.0.0.1`
`smolvm browser`	Start browser and desktop-style browser sessions
`smolvm windows`	Build a reusable Windows 11 `qcow2` image
`smolvm server`	Start the local SmolVM HTTP API
`smolvm ui`	Start the local dashboard
`smolvm bridge`	Check host Linux bridges before using bridged networking
`smolvm completion`	Install shell tab completion for `bash`, `zsh`, or `fish`
`smolvm doctor`	Check whether your host can run SmolVM
`smolvm update`	Upgrade SmolVM to the latest stable release
`smolvm image`	Pull, list, inspect, build, save, load, and prune cached sandbox images
`smolvm images`	Alias of `smolvm image list`
`smolvm prune`	Alias of `smolvm image prune` — remove image caches from older releases

Everyday sandbox workflow

Create a sandbox, open the fast shell, then stop it when you are done:

smolvm sandbox create --name my-sandbox
smolvm sandbox shell my-sandbox
smolvm sandbox stop my-sandbox

Use SSH when you specifically need a real SSH session:

smolvm sandbox ssh my-sandbox

List your sandboxes:

smolvm sandbox list --all

Run a single command in a sandbox from a script or agent — the guest’s exit code becomes smolvm’s exit code:

smolvm sandbox exec my-sandbox -- python --version

Read the host boot and console log when something goes wrong at startup:

smolvm sandbox logs my-sandbox --follow

macOS desktop workflow

On an Apple Silicon Mac, create a disposable macOS environment:

smolvm sandbox create --os macos --name nimble-mac

The create output confirms that the sandbox is running and includes the next command:

Next: smolvm sandbox desktop nimble-mac
Info: smolvm sandbox info nimble-mac

Run the Next command to open the sandbox in Screen Sharing:

smolvm sandbox desktop nimble-mac

Opened the desktop for sandbox 'nimble-mac'.

The first run prepares a reusable local image. See Disposable macOS environments for the one-time setup, requirements, and full create output.

Tab completion

Turn on tab completion so your shell can finish smolvm commands, options, and the names of your existing sandboxes:

smolvm completion bash --install   # also: zsh, fish

See smolvm completion for the manual setup and per-shell details.

Snapshot workflow

Create a checkpoint before a risky change, then restore it later:

smolvm sandbox snapshot create my-sandbox --snapshot-id before-change --resume-source
smolvm sandbox snapshot restore before-change --resume

File, env, and port workflow

Copy files, set environment variables, and expose a sandbox service:

smolvm sandbox file upload my-sandbox ./prompt.txt /workspace/prompt.txt
smolvm sandbox env set my-sandbox MODEL=gpt-4.1
smolvm sandbox port expose my-sandbox 8080:3000

Browser workflow

Start a browser sandbox with a live viewer:

smolvm browser start --live --json

The JSON response includes the session ID and viewer URLs. Use the session ID with other browser commands:

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

HTTP API workflow

Start the local API server when you want another process, script, or TypeScript client to manage SmolVM:

smolvm server start --host 127.0.0.1 --port 8000

See HTTP API and TypeScript SDK for endpoint and client examples.

Getting help

Display help for the main command:

smolvm --help

Display help for a subcommand:

smolvm sandbox create --help
smolvm sandbox snapshot create --help
smolvm server start --help

Next steps

Create a sandbox

Start a Linux, macOS, or Windows sandbox from the CLI

Open a shell

Use the fast shell or an SSH session

Copy files

Move files into and out of a sandbox

Snapshots

Save and restore sandbox state

HTTP API

Run the local API server

Dashboard UI

Launch the dashboard interface

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Install

Command groups

Everyday sandbox workflow

macOS desktop workflow

Tab completion

Snapshot workflow

File, env, and port workflow

Browser workflow

HTTP API workflow

Getting help

Next steps

Create a sandbox

Open a shell

Copy files

Snapshots

HTTP API

Dashboard UI

​Install

​Command groups

​Everyday sandbox workflow

​macOS desktop workflow

​Tab completion

​Snapshot workflow

​File, env, and port workflow

​Browser workflow

​HTTP API workflow

​Getting help

​Next steps

Create a sandbox

Open a shell

Copy files

Snapshots

HTTP API

Dashboard UI

Install

Command groups

Everyday sandbox workflow

macOS desktop workflow

Tab completion

Snapshot workflow

File, env, and port workflow

Browser workflow

HTTP API workflow

Getting help

Next steps