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
`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 doctor`	Check whether your host can run SmolVM
`smolvm update`	Upgrade SmolVM to the latest stable release
`smolvm prune`	Remove old image cache entries

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

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 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

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

​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

Snapshot workflow

File, env, and port workflow

Browser workflow

HTTP API workflow

Getting help

Next steps