CelestoAI/celesto

Celesto AI – Secure, Persistent Sandboxes for AI Agents

What it is – Celesto (formerly SmolVM) is an open‑source platform that gives large‑language‑model agents (Claude, Codex, Pi, etc.) a private, fast‑booting virtual computer they can run code on, browse the web, or use a full desktop environment. Each sandbox is a lightweight micro‑VM (Firecracker on Linux, KVM‑based Windows guests) that starts in ~500 ms, isolates the agent from the host at the hardware level, and can be kept alive across multiple API calls.

Why it matters – Running AI‑generated code directly on a developer’s laptop is risky. Celesto lets you execute that code in a throw‑away VM that can:

• Persist files and state between turns, enabling multi‑step workflows.
• Offer a real browser or full desktop for “computer‑use” agents.
• Enforce strict network policies (off, restricted CIDR, or full internet).
• Mount host directories read‑only or writable, so agents can work on existing codebases without copying files.
• Snapshot and resume VMs, or delete them automatically when a Python with block ends.

Core components

Component	What it does
Python SDK (celesto package)	High‑level Computer / Celesto classes to create, run commands, upload files, mount directories, open terminals, and manage browsers.
CLI (celesto command)	Create, list, stop, shell‑into, or delete sandboxes; launch browser or desktop sessions; manage Windows/macOS previews.
TypeScript preview (@celestoai/smolvm)	Node.js API for the same sandbox capabilities, useful for server‑side agents written in JavaScript/TypeScript.
Firecracker‑based Linux micro‑VMs	Sub‑second boot, hardware isolation, configurable networking, snapshot support.
Windows 11 guest support	Runs on a Linux host with KVM; provides PowerShell access and parallel sandboxing.
macOS desktop preview	On Apple‑silicon Macs, spins up a temporary macOS desktop for UI testing (requires ~50 GB download).

Typical use cases

• Safe execution of AI‑generated code – Run untrusted snippets without risking the host OS.
• Browser automation for agents – Give a LLM a live Chromium instance it can control via CDP, VNC, or a viewer URL.
• Code‑base assistance – Mount a project directory so an agent can read, edit, and commit changes inside the sandbox.
• Stateful multi‑turn workflows – Keep the same VM alive across several API calls to maintain context.
• Testing installers or GUI apps – Use the macOS or Linux desktop previews to automate UI interactions.

Getting started (quick‑start)

# Install the alpha package (Python 3.11+ required)
pip install 'celesto==0.0.15a0'

# Prepare host dependencies (may ask for sudo on Linux)
celesto setup
celesto doctor   # sanity‑check

from celesto import Computer

# A one‑off sandbox that prints a message
with Computer(local=True) as comp:
    out = comp.run("echo 'Hello from the sandbox!'")
    print(out.stdout)

The sandbox disappears when the with block ends. For a persistent VM, create it with lifetime="persistent" and reconnect later via Computer.get(id, local=True).

Running in the cloud – Set CELESTO_API_KEY and omit local=True. The same Python API works; cloud usage may incur charges.

CLI examples

# Create, list and stop a sandbox
celesto sandbox create --name demo
celesto sandbox list
celesto sandbox stop demo

# Open an interactive shell
celesto sandbox shell demo

# Run a single command (useful in scripts)
celesto sandbox exec demo -- python --version

Browser sandbox – Launch a visible Chromium instance and watch it live:

celesto browser start --live
# Viewer URL and VNC URL are printed; open the viewer in a browser to see the session.

In Python:

from celesto import Celesto
with Celesto.browser(headless=False) as b:
    print(b.viewer_url)   # open to watch
    print(b.cdp_url)      # feed to Playwright / CDP tools

Windows sandbox – Requires a Linux host with KVM. Build an image from an ISO or use a pre‑made QCOW2:

celesto windows build-image --iso Win11.iso --virtio-win-iso virtio-win.iso --output ~/.smolvm/images/win11.qcow2

Then use the Python API with os="windows".

Security & isolation

• Each sandbox runs in its own VM (hardware‑level separation).
• Network can be completely disabled or restricted to specific CIDR blocks.
• Filesystem mounts are read‑only by default; writable mounts must be explicitly requested.
• Snapshots capture full memory, disk, and process state for later resume.

Documentation & community

• Full docs: https://docs.celesto.ai
• Quick‑start, API reference, and guides for networking, macOS, Windows, and browser sandboxes.
• Discord community for support: https://discord.gg/KNb5UkrAmm

Maturity – The project is in an alpha release (0.0.15a0). Core Linux micro‑VM functionality is stable, while Windows and macOS previews are still experimental. CI badges show tests and CodeQL scans passing.

---

Bottom line – Celesto provides the plumbing to give LLM‑based agents their own fast, isolated computers, whether you need a headless command runner, a full browser, or a desktop UI. It abstracts away VM provisioning, networking, and persistence, letting developers focus on building AI‑driven workflows safely.