Run your first SmolVM microVM sandbox

By the end of this guide you’ll have an isolated Linux sandbox running on your machine, ready to execute commands safely.

Install SmolVM

curl -sSL https://celesto.ai/install.sh | bash

This installs everything you need and configures your machine. See Installation for manual install and requirements.

Run your first sandbox

Create quickstart.py:

quickstart.py

from smolvm import SmolVM

vm = SmolVM()
result = vm.run("echo 'Hello from the sandbox!'")
print(result.stdout.strip())
vm.stop()

Run it:

python quickstart.py

You should see:

Hello from the sandbox!

The first run takes 30-60 seconds to download the operating system images.

Prefer the command line?

You can do the same thing without writing any Python:

smolvm create --name my-sandbox
smolvm ssh my-sandbox       # opens a shell inside the sandbox — type `exit` to leave
smolvm stop my-sandbox

Configure memory and disk for heavier workloads (defaults: 512 MiB memory, 512 MiB disk):

from smolvm import SmolVM

vm = SmolVM(memory=2048, disk_size=4096)
result = vm.run("free -m")
print(result.stdout)
vm.stop()

Plug SmolVM into PydanticAI, OpenAI Agents, LangChain, and more

Expose services running inside a sandbox to your host machine

Build specialized images with your own tools pre-installed

Explore the complete SmolVM API

Join the Slack community to get help and share your use cases.

Last modified on May 28, 2026

⌘I