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

​
Options

​
string
Name for the sandbox. If you omit it, SmolVM creates a unique name.
​
string
Guest operating system image. Supported values are alpine, ubuntu, windows, and macos. Omit it for the default Linux image, pair windows with --image, or see Disposable macOS environments before using macos.
​
string
Image reference to boot. Use an S3 image URI, a file:// URI, or a local qcow2 path for Windows guests.
​
integer
Guest memory in MiB.
​
integer
Guest disk size in MiB.
​
string
Runtime backend. Choices are auto, firecracker, qemu, libkrun, and vz. SmolVM selects vz automatically for macOS guests.
​
string
default:"auto"
QEMU machine model. Choices are auto, q35, and microvm.
​
string
Host-to-guest control channel. Choices are ssh and vsock. Leave unset for auto-selection.
​
string
Share a host folder with the sandbox. Use HOST_PATH or HOST_PATH:GUEST_PATH. You can pass this option more than once.
​
flag
Allow writes to every shared folder from this command.
​
flag
default:"--clipboard"
Share the clipboard between your Mac and a macOS sandbox desktop. On by default for macOS guests. Use --no-clipboard to keep the two clipboards separate. The choice is saved with the sandbox and applies across stop and start. See Copy and paste between your Mac and the sandbox.
​
flag
Approve the one-time macOS image download and preparation without an interactive prompt.
​
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.
​
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.
​
number
default:"30"
Seconds to wait for the sandbox to become ready.
​
flag
Print a JSON envelope instead of formatted text.

​
Examples

​
Create a default sandbox

​
Create a named Ubuntu sandbox

​
Share a project folder

By default, shared folders are read-only. Add --writable-mounts only when the sandbox should edit host files directly.

​
Use QEMU microvm explicitly

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

See Windows sandboxes before running Windows guests.

​
Create a macOS desktop sandbox

The sandbox starts immediately when a prepared macOS image is available. The output shows its running status and the next command:
Open the desktop:
The first macOS sandbox asks before downloading and preparing a local image. See Disposable macOS environments for host requirements, one-time setup, and preview limits.

​
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 July 31, 2026