Celesto

Secure, persistent computers for AI agents

OpenMuse · Quickstart · Python API · Agents and automation · Runtimes · Examples · Docs · Discord

---

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 computer 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 computer instead of a process on your machine, Celesto provides a stronger boundary for untrusted code.

These docs use one word for each idea. See the glossary for what "computer", "desktop", and "browser session" mean, or browse the documentation index for guides.

Built with Celesto: OpenMuse

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.

Explore OpenMuse →

OpenMuse is a preview. Clone this repository to run it locally.

Quickstart

1. Install Celesto

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 | bash

Install Celesto with Python 3.11 or newer, prepare the machine, then check the setup:

pip install celesto
celesto setup
celesto doctor

On macOS, setup uses Homebrew to install QEMU. On Linux, setup may ask for sudo.

2. Create a computer

Give the computer a name so later commands can find it:

celesto computer create --name my-computer

celesto sandbox remains an equivalent spelling for every celesto computer subcommand. See older names you will still see.

3. Run a command

Everything after -- runs inside the computer:

celesto computer exec my-computer -- python --version

4. Delete the computer

Delete it when you no longer need its files or state:

celesto computer delete my-computer

Use celesto computer stop my-computer instead when you want to keep it for later. Restart it with celesto computer start my-computer.

Local CLI and Python SDK usage telemetry displays a notice before sending limited installation and feature counts. PostHog may infer approximate location from the request IP address. To turn telemetry off, run celesto config telemetry off or set CELESTO_NO_TELEMETRY=1 in your environment. See the CLI reference and privacy policy.

Use the Python API

The installer includes the Python SDK. The with block creates a local computer 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)

Run in Celesto Cloud

Cloud computers 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	What your machine needs
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

Start cloud computers with your packages installed

A custom template is a built-in template plus your own setup commands. Celesto runs the commands once and saves the result, so every cloud computer you create from the template starts with your packages ready:

from celesto import Template

template = Template.create(
    name="data-env",
    build_script="apt-get install -y ffmpeg\npip install pandas",
)
template.wait(on_log=print)  # prints the build log; returns when the build is ready

with template.create_computer() as computer:
    print(computer.run("ffmpeg -version").stdout)

The build script runs once, as root, and stops at the first failing command. Files can't be uploaded with it, so list packages directly instead of using pip install -r requirements.txt. Check a script first with Template.lint(script), load a template with Template.get("tpl_..."), or pass its ID as CloudComputer(template_id="tpl_..."). See the custom templates guide for limits, errors, and rebuilding.

Agents and automation

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 --json

This is the beginning of the README. Read the rest at the original. Read the full README ↗