Quick start • Examples • Features • Performance • Docs • Discord

Celesto gives AI agents their own secure and persistent computer. Each microVM boots in milliseconds, runs any code or software you throw at it, persists files and state across sessions, and disappears when you're done — ready to handle thousands of sandboxes in production.

Quickstart

Install Celesto and prepare your machine with one command:

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

pip install 'celesto==0.0.15a0'

celesto setup
celesto doctor

Start a sandbox in Python

Run a local sandbox:

from celesto import Computer

computer = Computer()
result = computer.run("echo 'Hello from local sandbox!'")
print(result.stdout)
computer.stop()

By default, Computer runs locally. To run in the cloud, set CELESTO_API_KEY in your environment and use provider="cloud".

from celesto import Computer

computer = Computer(provider="cloud")
result = computer.run("echo 'Hello from cloud sandbox!'")
print(result.stdout)
computer.stop()

Start a sandbox from the CLI

Create a sandbox, check that it's running, then stop it:

celesto sandbox create --name my-sandbox
# my-sandbox  running  172.16.0.2

celesto sandbox list
# NAME         PRESET  STATUS   PID
# my-sandbox   -       running  12345

celesto sandbox stop my-sandbox

Open a shell inside a running sandbox:

celesto sandbox shell my-sandbox

Use celesto sandbox ssh my-sandbox when you specifically need an SSH session.

Run a single command in a running sandbox without opening a shell — useful in scripts. Put the command after --, and add --start if you want a stopped sandbox started first:

celesto sandbox exec my-sandbox -- python --version

If something goes wrong, read the sandbox's logs (add --follow to watch them live):

celesto sandbox logs my-sandbox

Tip: turn on tab completion so your shell can finish commands and sandbox names for you — run celesto completion bash --install (or zsh, fish) once. See the CLI reference for details.

Browser sandbox

Celesto can also start a full browser inside a sandbox. This is useful when agents need to navigate websites, fill out forms, take screenshots, or connect through VNC.

Start a visible browser sandbox from Python:

from celesto import Celesto

with Celesto.browser(headless=False) as browser:
    print(browser.cdp_url)  # Automation endpoint for Playwright or CDP tools
    print(browser.viewer_url)  # Web URL you can open to watch live
    print(browser.display_url)  # VNC URL for clients or computer-use agents

Use browser.cdp_url when a browser automation tool needs a Chromium DevTools connection address. Use browser.viewer_url when you want to watch the session in your own browser. Use browser.display_url when a VNC client or computer-use agent needs to control the screen.

Start the same browser sandbox from the CLI:

celesto browser start --live
# Sandbox: browser-a1b2c3d4
# Viewer URL: http://127.0.0.1:36080/vnc.html?autoconnect=1&resize=scale  # open in a browser
# Display URL: vnc://127.0.0.1:35900                                      # give to a VNC client or agent

Use Celesto.browser(headless=True) for browser automation only; it gives you cdp_url and no visible viewer. Use Celesto.browser(headless=False) for a visible browser; it gives you cdp_url, viewer_url, and display_url. A browser sandbox is still a focused Chromium environment, not a general desktop.

Open the viewer URL to watch the browser in real time, or give the display URL to a computer-use agent or VNC client. When you're done, list and stop sandboxes:

celesto browser list
celesto browser stop sess_a1b2c3

See examples/browser_sandbox.py for a complete Python example.

Network controls

Sandboxes have internet access by default. On Linux with Firecracker, turn outbound access off while keeping commands and file transfers available through a direct connection (vsock):

from celesto import Celesto

with Celesto(
    backend="firecracker",
    comm_channel="vsock",
    internet_settings={"mode": "off"},
) as vm:
    print(vm.run("echo hello").stdout)

Use mode="restricted" with allowed_cidrs to allow specific IPv4 addresses or ranges. These modes require private networking and do not support shared folders or exposed ports. Command output and explicit file downloads still work when outbound access is off.

Existing allowed_domains lists allow the IP addresses found during setup; they do not verify the hostname on each connection. DNS servers are not automatically allowed.

See the networking guide for a restricted-access example and supported configurations.

Mount host directories

You can give a sandbox access to a folder on your machine. This is useful when an agent needs to work with an existing project without copying files back and forth.

celesto sandbox create --name my-sandbox --mount ~/Projects/my-app
celesto sandbox shell my-sandbox
ls /workspace   # your host files appear here

By default the host folder is read-only — the sandbox can read every file, but changes stay inside the sandbox and never touch the originals. If the agent creates or edits files under /workspace, those changes live only in the VM's overlay layer.

Mount at a custom path, or mount multiple directories:

celesto sandbox create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data

When you do want the sandbox to edit your host files, add --writable-mounts:

celesto sandbox create --mount ~/Projects/my-app --writable-mounts

Every directory passed with --mount becomes writable; writes from the guest are visible on the host immediately. The flag applies to all mounts on that command, so don't pair a folder you want the sandbox to modify with one you want kept untouched.

The same works from Python:

from celesto import Celesto

with Celesto(mounts=["~/Projects/my-app"], writable_mounts=True) as vm:
    vm.run("echo hello > /workspace/from-sandbox.txt")

Upload a file

You can copy one file into a running sandbox without mounting a whole folder. This is useful when an agent needs a config file, script, or small input file.

# Copy a file from your machine into the sandbox.
celesto sandbox file upload my-sandbox ./prompt.txt /tmp/prompt.txt

# Open a shell in the sandbox to confirm the file is there.
celesto sandbox shell my-sandbox
# Then, inside the sandbox shell:
cat /tmp/prompt.txt

For a temporary, one-shot sandbox, the same works from Python. The sandbox and uploaded file are deleted when the context exits:

from celesto import Celesto

with Celesto() as vm:
    vm.upload_file("./prompt.txt", "/tmp/prompt.txt")

The destination must be an absolute path inside the sandbox (starting with /), and any existing file at that path is overwritten.

macOS desktop sandbox (preview)

On an Apple Silicon Mac, Celesto can open a temporary macOS desktop for testing apps and installers without changing your everyday system. The first run downloads macOS from Apple and prepares a reusable local image.

celesto setup --macos

Create the desktop sandbox:

celesto sandbox create --os macos --name test-mac
# Next: celesto sandbox desktop test-mac

Open it in the built-in Screen Sharing app:

celesto sandbox desktop test-mac

Image preparation needs about 50 GB and 20–40 minutes. macOS images stay on the Mac that created them, and at most two macOS guests can run at once. See the macOS desktop guide for shared folders, limits, and cleanup.

Windows sandbox

Celesto can boot a Windows 11 guest as well as Linux. Hand it a Windows image and you get the same Python and CLI you use for Linux — run PowerShell, upload files, set environment variables, and run many sandboxes in parallel from one baseline image.

from celesto import Celesto

with Celesto(
    os="windows",
    image="~/.smolvm/images/win11.qcow2",
    ssh_user="smolvm",
    ssh_password="smolvm",
) as vm:
    print(vm.run("Write-Output 'hello from windows'").stdout)

Build your own image from a Windows ISO:

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

Windows guests need a Linux host with KVM. Host mounts, network controls, and snapshots are Linux-only today. See the full Windows guide for details.

Coding agents

It sucks to “press enter and accept changes” every few seconds while using coding agents. Celesto makes it easy to isolate the agent coding environment from the host (laptops).

Start any supported coding agent in its own sandbox:

Video tutorial:

celesto codex start
celesto claude start
celesto pi start
celesto hermes start
celesto opencode start
celesto openclaw start --name openclaw-work --no-attach

OpenClaw also has a private browser dashboard. Open it after the named sandbox starts:

celesto openclaw list
# NAME              STATUS   PID
# openclaw-work     running  12345

celesto openclaw open-ui openclaw-work

Creating an OpenClaw sandbox currently takes several minutes while Celesto installs its supported Node.js runtime and pinned OpenClaw release. See the OpenClaw guide for credentials, the dashboard flow, and safe steps for replacing an older sandbox.

Linux computer

Use a Linux computer when an agent needs a visible desktop with more than a browser. The built-in template includes Chromium, a terminal, a file manager, and a text editor.

During this preview, the first computer start builds its image locally and requires Docker. Later starts reuse the cached image.

from celesto import Celesto

with Celesto.computer() as computer:
    print(computer.display.viewer_url)
    print(computer.browser.cdp_url)
    computer.files.write("/workspace/task.txt", "Review this file")
    print(computer.run("ls -la /workspace").stdout)

The API groups the screen under computer.display and Chromium under computer.browser. If Chromium is closed while the desktop remains open, call computer.browser.launch().

From the CLI:

celesto computer start --name assistant
celesto computer open assistant
celesto computer delete assistant

Choose a normal sandbox for command-only work, a browser sandbox for web-only automation, and a Linux computer for work across desktop applications. See the Linux computer guide for Python and TypeScript examples.

Examples

Getting started

Agent framework integrations

These examples show how to wrap Celesto as a tool for popular agent frameworks, so an AI model can run shell commands or drive a browser through your sandbox.

Advanced

Each script shows its own pip install ... line when it needs extra packages.

Security

Celesto automatically trusts new sandboxes on first connection to keep setup simple. This is safe for local development, but you should not expose sandbox network ports publicly without extra controls. See SECURITY.md for the full policy and scope.

Performance

Celesto ships a benchmark suite that measures the timings AI agents actually feel: cold start, time-to-interactive, pause/resume, and snapshot create/restore. It drives the public Python SDK on whichever backend is native to your host — Firecracker on Linux, QEMU on macOS.

Run it locally:

uv run python scripts/benchmarks/bench.py

See scripts/benchmarks/README.md for flags, output format, and what each metric means.

Contributing

See CONTRIBUTING.md to get started.

License

Apache 2.0 — see LICENSE for details.