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 sandbox create --name my-sandbox
smolvm sandbox ssh my-sandbox       # opens a shell inside the sandbox — type `exit` to leave
smolvm sandbox stop my-sandbox

Customize resources

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

Next steps

AI agent integration

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

Port forwarding

Expose services running inside a sandbox to your host machine

Custom images

Build specialized images with your own tools pre-installed

API reference

Explore the complete SmolVM API

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

Last modified on June 30, 2026

⌘I

Get Started

Features

Guides

Architecture

Operations

Run your first SmolVM microVM sandbox

Prefer the command line?

Customize resources

Next steps

AI agent integration

Port forwarding

Custom images

API reference

​Prefer the command line?

​Customize resources

​Next steps

AI agent integration

Port forwarding

Custom images

API reference

Prefer the command line?

Customize resources

Next steps