Skip to main content

​
Synopsis

smolvm create --name <name> [OPTIONS]

​
Description

The create command spins up a new VM with a name you choose, waits for it to be SSH-ready, and leaves it running. This is useful when you need a persistent VM that you can reconnect to later using smolvm ssh.

​
Options

​
--name
string
required
A unique identifier for the VM. Use this name to reference the VM in other commands like smolvm ssh and smolvm env.
​
--memory-mib
integer
default:"512"
Guest memory in MiB.
​
--disk-size-mib
integer
default:"512"
Root filesystem size in MiB.
​
--backend
string
default:"auto"
Backend override. Choices: auto, firecracker, qemu. The auto option selects the best backend for your platform.
​
--boot-timeout
float
default:"30"
Seconds to wait for VM boot and SSH readiness.

​
Examples

​
Create a VM with default settings

smolvm create --name my-agent
Example output: 
Created VM 'my-agent'.
  Backend: firecracker
  IP address: 172.16.0.2
  SSH port: 2222
  Next: smolvm ssh my-agent

​
Create a VM with more resources

smolvm create --name heavy-workload --memory-mib 2048 --disk-size-mib 4096

​
Specify a backend

smolvm create --name dev-env --backend qemu

​
Increase boot timeout for slower systems

smolvm create --name slow-start --boot-timeout 60

​
What happens during create

  1. SmolVM configures a new VM with the specified settings (or defaults)
  2. The VM process starts with the selected backend
  3. SmolVM waits for the VM to boot and become SSH-ready
  4. Once ready, the VM stays running in the background
After creation, you can connect with smolvm ssh <name> or use the Python SDK with SmolVM.from_id("<name>").

​
Exit codes

CodeDescription
0Success - VM created and SSH-ready
1Error - VM creation or boot failed
Last modified on March 29, 2026