Skip to main content

​
Synopsis

smolvm create [-n <name>] [--os <os>] [OPTIONS]

​
Description

The create command spins up a new VM, waits for it to be SSH-ready, and leaves it running. You can give it a name or let SmolVM generate one automatically. Use smolvm ssh to connect to the VM afterwards.

​
Options

​
--name, -n
string
A unique identifier for the VM. If you skip this flag, SmolVM auto-generates a name like vm-a1b2c3d4. Use this name to reference the VM in other commands like smolvm ssh and smolvm stop.
​
--os
string
default:"alpine"
Guest operating system. Choices: alpine, ubuntu. Alpine is smaller and boots faster. Ubuntu provides a more complete Linux environment with apt.
​
--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 an auto-generated name

smolvm create
SmolVM picks a unique name for you (for example, vm-a1b2c3d4) and prints it after the VM is ready. You can then use that name with smolvm ssh and other commands. Example output: 
Created VM 'vm-a1b2c3d4'.
  Backend: firecracker
  IP address: 172.16.0.2
  SSH port: -
  Next: smolvm ssh vm-a1b2c3d4

​
Create a VM with a custom name

smolvm create -n 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

​
Create an Ubuntu VM

smolvm create -n dev-env --os ubuntu
Ubuntu VMs give you apt and a more familiar Linux environment. They take slightly longer to boot than Alpine.

​
Specify a backend

smolvm create -n dev-env --backend qemu

​
Increase boot timeout for slower systems

smolvm create --boot-timeout 60

​
What happens during create

  1. SmolVM configures a new VM with the specified settings (or defaults)
  2. If you did not provide --name, SmolVM generates a unique identifier
  3. The VM process starts with the selected backend
  4. SmolVM waits for the VM to boot and become SSH-ready
  5. 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 April 5, 2026