Skip to main content
smolvm sandbox create starts a new sandbox and leaves it running. Give it a name when you want to use the same sandbox in later commands, or let SmolVM generate one for you.

​
Synopsis

smolvm sandbox create [OPTIONS]

​
Options

​
--name, -n
string
Name for the sandbox. If you omit it, SmolVM creates a unique name.
​
--os
string
Guest operating system image. Supported values are alpine, ubuntu, and windows. Omit it for the default Linux image, or pair windows with --image.
​
--image
string
Image reference to boot. Use an S3 image URI, a file:// URI, or a local qcow2 path for Windows guests.
​
--memory
integer
Guest memory in MiB.
​
--disk-size
integer
Guest disk size in MiB.
​
--backend
string
Runtime backend. Choices are auto, firecracker, qemu, and libkrun.
​
--qemu-machine
string
default:"auto"
QEMU machine model. Choices are auto, q35, and microvm.
​
--comm-channel
string
Host-to-guest control channel. Choices are ssh and vsock. Leave unset for auto-selection.
​
--mount
string
Share a host folder with the sandbox. Use HOST_PATH or HOST_PATH:GUEST_PATH. You can pass this option more than once.
​
--writable-mounts
flag
Allow writes to every shared folder from this command.
​
--boot-timeout
number
default:"30"
Seconds to wait for the sandbox to become ready.
​
--json
flag
Print a JSON envelope instead of formatted text.

​
Examples

​
Create a default sandbox

smolvm sandbox create

​
Create a named Ubuntu sandbox

smolvm sandbox create --name dev-env --os ubuntu --disk-size 4096

​
Share a project folder

smolvm sandbox create \
  --name code-review \
  --mount ~/Projects/my-app:/workspace
By default, shared folders are read-only. Add --writable-mounts only when the sandbox should edit host files directly.

​
Use QEMU microvm explicitly

smolvm sandbox create \
  --name qemu-fast-path \
  --backend qemu \
  --qemu-machine microvm

​
Create a Windows sandbox from a local image

smolvm sandbox create \
  --name win11-test \
  --os windows \
  --image ~/.smolvm/images/win11.qcow2
See Windows sandboxes before running Windows guests.

​
What happens

  1. SmolVM resolves the image, backend, and control channel.
  2. It creates a per-sandbox disk and network configuration.
  3. It starts the sandbox and waits for the guest to be ready.
  4. It prints the sandbox name and suggested next commands.
Last modified on June 24, 2026