Celesto gives an AI agent its own computer for running code, browsing the web, and using desktop apps. You can run that computer on your machine during development or in Celesto Cloud for remote and production work.
Each sandbox is a lightweight virtual machine, starts in about 500 ms, and can keep files and state between sessions. Because the agent runs in a separate virtual machine instead of a process on your computer, Celesto provides a stronger boundary for untrusted code.
OpenMuse is our open-source computer coworker, built end to end on Celesto. It browses public websites in its own disposable Linux desktop while you watch, approve clicks and form changes, or take control.
OpenMuse is a preview. Clone this repository to run it locally.
On Linux or macOS, this command installs the Celesto CLI and Python SDK, prepares the machine, and checks that it is ready:
curl -fsSL https://celesto.ai/install.sh | bashManual local setup
Install Celesto with Python 3.11 or newer, prepare the machine, then check the setup:
pip install celesto
celesto setup
celesto doctorOn macOS, setup uses Homebrew to install QEMU. On Linux, setup may ask for sudo.
Give the sandbox a name so later commands can find it:
celesto sandbox create --name my-sandboxEverything after -- runs inside the sandbox:
celesto sandbox exec my-sandbox -- python --versionDelete it when you no longer need its files or state:
celesto sandbox delete my-sandboxUse celesto sandbox stop my-sandbox instead when you want to keep it for later. Restart it with celesto sandbox start my-sandbox.
The installer includes the Python SDK. The with block creates a local sandbox when the block starts and deletes it when the block ends:
from celesto import Computer
with Computer() as computer:
result = computer.run("echo 'Hello from Celesto!'")
print(result.stdout)Cloud sandboxes do not require virtualization software on your machine. First, set your API key:
export CELESTO_API_KEY="your-api-key"Then run the same Python code with the cloud provider:
from celesto import Computer
with Computer(provider="cloud") as computer:
result = computer.run("echo 'Hello from Celesto Cloud!'")
print(result.stdout)| Provider | Best for | Host requirements |
|---|---|---|
| Local | Development, tests, and private workloads on your machine | Local virtualization setup |
| Cloud | Remote tasks, persistent workspaces, and production workloads | Python package and CELESTO_API_KEY |
Celesto commands print readable output by default. Add --json when a script or agent needs stable, machine-readable output. Every JSON response contains ok, command, exit_code, data, and error fields.
Check the machine before accepting work. --strict makes warnings fail the check:
celesto doctor --strict --jsonCreate a named sandbox and capture the JSON response:
celesto sandbox create --name agent-job --jsonRun a command without opening an interactive shell:
celesto sandbox exec agent-job --json -- python -m pytestAlways clean up the sandbox by its exact name when the job ends:
celesto sandbox delete agent-job --jsonUse unique names for concurrent jobs. Prefer exec for automation; reserve shell, ssh, and desktop for interactive work. Commands return a nonzero exit code on failure, and JSON errors include a recovery command when Celesto can provide one.
For a coding agent with its CLI already installed, start a preset directly:
celesto codex startCelesto also provides presets for Claude Code, Pi, Hermes, OpenCode, and OpenClaw. See the agent presets guide for credentials, naming, and unattended usage.
Use celesto sandbox list to see sandboxes, celesto sandbox logs my-sandbox to inspect startup output, or celesto sandbox shell my-sandbox to open a fast interactive shell.
Add --follow to stream logs. Use celesto sandbox ssh my-sandbox when you need an SSH session. See the CLI reference for every command and shell completion.
Celesto exposes one default API and focused APIs for browser and desktop work:
| Runtime | Use it when an agent needs | Python API | CLI |
|---|---|---|---|
| Shell sandbox | Commands, code, and files | Computer() |
celesto sandbox |
| Browser | Chromium, CDP, screenshots, or a live viewer | Celesto.browser() |
celesto browser |
| Linux computer | A full desktop and multiple GUI apps | Celesto.computer() |
celesto computer |
| Windows sandbox | PowerShell or Windows software | Celesto(os="windows", ...) |
— |
| macOS desktop | App or installer tests on Apple Silicon | — | celesto sandbox create --os macos |
Use Computer for the common command sandbox path. Use the Celesto factories for focused browser and desktop runtimes. Use Celesto(...) directly when you need low-level VM options such as the backend, communication channel, guest OS, mounts, or network policy.
| Capability | What it provides |
|---|---|
| Fast start | A ready microVM in about 500 ms, without an image pull on each start |
| VM isolation | A separate virtual machine for each sandbox |
| Local or cloud | The same Computer API across development and production |
| Persistent state | Files and state that survive across sessions |
| Host mounts | Read-only or writable access to selected local directories |
| Snapshots | Pause and restore memory, disk, and active processes |
| Network policy | Disable outbound access or allow specific IPv4 ranges on Linux with Firecracker |
| Multiple operating systems | Linux, Windows 11, and macOS preview support |
Use a browser sandbox when an agent only needs Chromium. Celesto exposes a CDP endpoint for automation and, in visible mode, URLs for live view and screen control.
from celesto import Celesto
with Celesto.browser(headless=False) as browser:
print(browser.cdp_url)
print(browser.viewer_url)
print(browser.display_url)cdp_url: connect Playwright or another CDP client.viewer_url: watch the browser from another browser.display_url: connect a VNC client or computer-use agent.
Use headless=True when the agent only needs CDP. Start a visible browser from the CLI with:
celesto browser start --liveSee examples/browser_sandbox.py for a complete example.
Use a Linux computer when an agent needs a visible desktop with more than a browser. The default image includes Chromium, a terminal, a file manager, and a text editor.
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 screen access under computer.display and Chromium access under computer.browser. If Chromium closes while the desktop stays active, call computer.browser.launch().
The first start downloads and verifies the Linux desktop image. Later starts reuse the cached image, so Docker is not required.
celesto computer start --name assistant
celesto computer open assistant
celesto computer delete assistantSee the Linux computer guide for Python and TypeScript examples.
Use a Windows sandbox when an agent must run PowerShell or Windows software. Celesto can boot Windows 11 from a baseline image, upload files, set environment variables, and start multiple guests from the same image.
from celesto import Celesto
with Celesto(
os="windows",
image="~/.celesto/images/win11.qcow2",
ssh_user="celesto",
ssh_password="celesto",
) as vm:
print(vm.run("Write-Output 'hello from windows'").stdout)Create an image from a Windows ISO:
celesto windows build-image \
--iso ./Win11.iso \
--virtio-win-iso ./virtio-win.iso \
--output ~/.celesto/images/win11.qcow2Windows guests require a Linux host with KVM. Host mounts, network controls, and snapshots remain Linux-only. See the Windows guide for image setup and guest requirements.
On an Apple Silicon Mac, Celesto can create a temporary macOS desktop for app and installer tests without changes to your main system.
Prepare the reusable local image:
celesto setup --macosCreate and open a desktop:
celesto sandbox create --os macos --name test-mac
celesto sandbox desktop test-macThe first setup downloads macOS from Apple, requires about 50 GB, and takes 20–40 minutes. The image stays on the Mac that created it. Celesto supports at most two macOS guests at once. See the macOS desktop guide for limits, shared folders, and cleanup.
Give a local sandbox access to an existing project without a copy step:
celesto sandbox create --name my-sandbox --mount ~/Projects/my-app
celesto sandbox shell my-sandbox
ls /workspaceHost mounts are read-only by default. The sandbox can read the source files, but writes under /workspace stay in the VM overlay and do not change the host copy.
Choose a guest path or mount multiple directories:
celesto sandbox create \
--mount ~/Projects/my-app:/code \
--mount ~/data:/mnt/dataAdd --writable-mounts only when the sandbox must change the host files:
celesto sandbox create \
--mount ~/Projects/my-app \
--writable-mountsThe flag applies to every mount in that command. Do not combine a writable project directory with a directory that must remain unchanged.
The same option exists in Python:
from celesto import Celesto
with Celesto(mounts=["~/Projects/my-app"], writable_mounts=True) as vm:
vm.run("echo hello > /workspace/from-sandbox.txt")Copy a config, script, or small input into a live sandbox:
celesto sandbox file upload my-sandbox ./prompt.txt /tmp/prompt.txtOr upload a file to a temporary sandbox from Python:
from celesto import Celesto
with Celesto() as vm:
vm.upload_file("./prompt.txt", "/tmp/prompt.txt")The destination must be an absolute guest path. Celesto replaces any file that already exists at that path.
Sandboxes have internet access by default. On Linux with Firecracker, use vsock to keep command and file-transfer access while you disable outbound network access:
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. The restricted modes require private network mode and do not support host mounts or exposed ports. Explicit command output and file downloads still work when outbound access is off.
An allowed_domains list resolves domains during setup and permits the resulting IP addresses. It does not check the hostname on each connection. DNS servers do not receive automatic access. See the network guide for supported combinations.
Run a supported code agent in its own sandbox so it can edit and execute code without direct access to your host environment:
celesto codex start
celesto claude start
celesto pi start
celesto hermes start
celesto opencode start
celesto openclaw start --name openclaw-work --no-attachOpen the private OpenClaw dashboard after the sandbox starts:
celesto openclaw open-ui openclaw-workThe first OpenClaw start can take several minutes while Celesto installs its supported Node.js runtime and pinned OpenClaw release. See the agent presets guide for credentials and dashboard access.
| Goal | Example |
|---|---|
| Run code in a sandbox | quickstart_sandbox.py |
| Start a browser sandbox | browser_sandbox.py |
| Pass environment variables | env_injection.py |
| Framework or task | Example |
|---|---|
| OpenAI Agents | openai_agents_tool.py |
| LangChain | langchain_tool.py |
| PydanticAI shell tool | pydanticai_tool.py |
| PydanticAI sandbox across turns | pydanticai_reusable_tool.py |
| PydanticAI browser automation | pydanticai_agent_browser.py |
| Computer use | computer_use_browser.py |
Each example includes any extra package command it requires.
Each sandbox runs in its own virtual machine, which provides a stronger isolation boundary than process-level containers. Isolation still depends on secure host, hypervisor, image, credential, mount, and network configuration.
Celesto trusts a new local sandbox on its first connection to simplify development. Do not expose sandbox ports to the public internet without authentication and network controls. Treat writable mounts, forwarded credentials, and host-accessible services as explicit trust decisions.
See SECURITY.md for the security policy, threat model, and disclosure process.
The benchmark suite measures cold start, time to interactive, pause and resume, and snapshot create and restore. It uses the public Python SDK with the native host backend: Firecracker on Linux and QEMU on macOS.
uv run python scripts/benchmarks/bench.pySee the benchmark guide for flags, output, and metric definitions.
See CONTRIBUTING.md to set up a development environment and submit a change. Coding agents should also read AGENTS.md for repository-specific commands, CLI conventions, release checks, and writing guidelines before editing the project.
Apache 2.0. See LICENSE for details.
Built with 🧡 by Celesto AI