smolvm sandbox create

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.

--network

string

default:"nat"

Network mode for the sandbox. Choices are nat (default, private SmolVM network with NAT, port forwarding, and domain controls) and bridge (attach directly to an existing host bridge on Linux). See Bridged networking.

--bridge

string

Name of the Linux bridge to attach to. Required with --network bridge and rejected otherwise. Run smolvm bridge check BRIDGE first to verify the bridge.

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

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

Attach a sandbox to a host bridge

On Linux, connect the sandbox directly to an existing bridge so it appears as a regular machine on that network with its own MAC and guest-managed IP:

smolvm bridge check br10
smolvm sandbox create --name demo --os alpine --network bridge --bridge br10

In bridge mode, SSH from the host, host port forwards, workspace mounts, and outbound-domain allow-lists are unavailable — use smolvm sandbox shell and connect to guest services over the bridged network instead. See Bridged networking for the full setup, tradeoffs, and SDK usage.

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

SmolVM resolves the image, backend, and control channel.
It creates a per-sandbox disk and network configuration.
It starts the sandbox and waits for the guest to be ready.
It prints the sandbox name and suggested next commands.

smolvm sandbox shell - Open the fast shell
smolvm sandbox ssh - Open an SSH session
smolvm sandbox list - View sandboxes
smolvm sandbox delete - Delete one or more sandboxes

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

smolvm sandbox create

Synopsis

Options

Examples

Create a default sandbox

Create a named Ubuntu sandbox

Use QEMU microvm explicitly

Attach a sandbox to a host bridge

Create a Windows sandbox from a local image

What happens

​Synopsis

​Options

​Examples

​Create a default sandbox

​Create a named Ubuntu sandbox

​Share a project folder

​Use QEMU microvm explicitly

​Attach a sandbox to a host bridge

​Create a Windows sandbox from a local image

​What happens

​Related commands

Synopsis

Options

Examples

Create a default sandbox

Create a named Ubuntu sandbox

Share a project folder

Use QEMU microvm explicitly

Attach a sandbox to a host bridge

Create a Windows sandbox from a local image

What happens

Related commands