Celesto

Celesto runs AI agents and harnesses in a cloud computer. An AI agent is software that can plan and run tasks. A harness is the code that starts, tests, or supervises an agent. They can run commands, write files, and use tools without touching your machine.

Use Celesto when you want to:

• Run an AI agent or harness in a clean computer.
• Run shell commands from Python, JavaScript, TypeScript, or the command line.
• Keep agent work separate from your laptop, server, or production system.
• Manage a computer from start to finish: create, list, run commands, stop, start, and delete.

This README covers the Python SDK, which is a code package, and the CLI, which is the celesto command. The JavaScript and TypeScript SDK is also available as @celestoai/sdk.

Install

Install the Python package to get both the SDK and the celesto command:

pip install celesto

Celesto requires Python 3.10 or newer.

For JavaScript and TypeScript projects, install the npm package:

npm install @celestoai/sdk

Get an API Key

An API key is a secret token that lets Celesto know a request is yours. Create one in Celesto Settings under Settings > Security.

For SDK code, set the key in your shell before running your program:

export CELESTO_API_KEY="your-api-key"

For CLI commands, you can save the key once:

celesto auth login

The CLI stores the key in your operating system's secure credential store. On Linux machines without a credential store, it saves the key in $XDG_CONFIG_HOME/celesto/credentials.json when XDG_CONFIG_HOME is set, or ~/.config/celesto/credentials.json otherwise, with user-only file permissions. SDK code does not read that saved CLI key; it reads CELESTO_API_KEY or the api_key value you pass to Computer.

Create a Computer from Python

This example creates a minimal Ubuntu computer, runs one command, prints the output, and deletes the computer. Celesto uses the scratch template by default.

from celesto import Computer

computer = Computer()
try:
    print(f"Computer ready: {computer.name}")

    result = computer.run("uname -a")
    print(result["stdout"])
finally:
    computer.delete()

To pass the key directly instead of using CELESTO_API_KEY:

from celesto import Computer

computer = Computer(api_key="your-api-key")
try:
    result = computer.run("uname -a")
    print(result["stdout"])
finally:
    computer.delete()

Manage Computers from the CLI

Run these commands in a macOS or Linux shell after celesto auth login. The first command creates a computer with the default scratch template.

celesto computer create
#   Name:   curie
#   ID:     cmp_123
#   Status: creating

For later examples, save the generated name in COMPUTER_NAME. The command uses --json so Python can read the output.

COMPUTER_NAME=$(
  celesto computer create --json |
  python3 -c 'import json, sys; print(json.load(sys.stdin)["name"])'
)

Inspect that computer by name or ID:

celesto computer get "$COMPUTER_NAME"
#   Name:   curie
#   ID:     cmp_123
#   Status: running

List your computers:

celesto computer list

Filter the list by status:

celesto computer list --status running

Filter the list by template. Template IDs come from celesto computer templates; browser-agent is one ready-made template.

celesto computer list --template browser-agent

Filter the list by project. Replace proj_123 with a project ID from your Celesto workspace.

celesto computer list --project proj_123

Limit the number of computers returned:

celesto computer list --limit 10

Run a command in the computer:

celesto computer run "$COMPUTER_NAME" "uname -a"

Use a longer timeout for slow commands. The value is in seconds and must be between 1 and 300.

celesto computer run "$COMPUTER_NAME" "sleep 10 && echo done" --timeout 30

Stream output while a command is still running:

celesto computer run "$COMPUTER_NAME" "for i in 1 2 3; do echo $i; sleep 1; done" --stream
# 1
# 2
# 3

celesto computer run --json prints one JSON object for scripts and exits with the same exit code as the remote command. celesto computer run --stream --json prints one compact JSON event per line.

Current caveat: commands run as the computer image's default exec user. The CLI and SDK do not yet expose a --user option. Run whoami first if your script depends on a specific home directory or file permission.

List templates when you want a computer with tools already installed:

celesto computer templates

Create a computer from a template:

celesto computer create --template coding-agent

Publish port 8000 when a process in the computer needs a public URL:

celesto computer port publish "$COMPUTER_NAME" --port 8000
# https://p-test.celesto.ai

List published ports:

celesto computer port list "$COMPUTER_NAME"

Unpublish the port when you are done:

celesto computer port unpublish "$COMPUTER_NAME" --port 8000

To open an interactive terminal, connect to the same computer:

celesto computer ssh "$COMPUTER_NAME"

Press Ctrl+] to exit the terminal, then delete the computer:

celesto computer delete --force "$COMPUTER_NAME"

Use celesto computer list to see the computers in your account.

Manage Computers from JavaScript or TypeScript

In an ESM or TypeScript file:

import { Computer } from "@celestoai/sdk";

const computer = await Computer.create();
try {
  console.log(`Computer ready: ${computer.name}`);

  const result = await computer.run("uname -a");
  console.log(result.stdout);
} finally {
  await computer.delete();
}

See the JavaScript and TypeScript README for Node.js requirements, Gatekeeper examples, and terminal connection details.

Python Computers API

Use the Python SDK when you want Celesto inside an app, script, or agent.

Create

from celesto import Computer

computer = Computer(cpus=2, memory=2048, disk="15gb")
try:
    print(computer.name, computer["name"])
finally:
    computer.delete()

Omit CPU, memory, or disk fields to use the default size. disk accepts MB as an integer or strings such as "2gb".

Templates

By default, Celesto uses scratch, a minimal Ubuntu computer. Use a template when you want a computer that already has extra tools installed. For example, coding-agent includes common tools for coding tasks.

List available templates:

from celesto import Computer

templates = Computer.list_templates()
for template in templates:
    print(template["id"], template.get("preinstalled_tools", []))

Template responses may include metadata such as aliases, capabilities, preinstalled tools, recommended uses, default published ports, and browser support flags. Older template records may omit those fields, so use .get() when your code can run against multiple API versions.

Create a computer from a template:

from celesto import Computer

computer = Computer(template_id="coding-agent")
try:
    print(computer.name)
finally:
    computer.delete()

Run a Command

from celesto import Computer

computer = Computer()
try:
    result = computer.run("ls -la", timeout=60)
    print(result["exit_code"])
    print(result["stdout"])
    print(result["stderr"])
finally:
    computer.delete()

The timeout value is the remote command timeout in seconds. The SDK gives the HTTP request a little more time than the command itself so slow command output can still return cleanly.

Current caveat: run() and exec() run as the computer image's default exec user. The SDK does not yet expose a user selector.

List, Stop, Start, and Delete

computer_id can be computer.id from Computer() or a computer name shown by celesto computer list.

Filter a list when you only want matching computers:

from celesto import Computer

computers = Computer.list(status="running", template_id="browser-agent")
for computer in computers:
    print(computer["name"])

Publish Ports

Publish a port when a service inside the computer needs a public URL:

from celesto import Computer

computer = Computer.get("curie")
url = computer.publish_port(8000)
print(url)

List and remove published ports:

from celesto import Computer

computer = Computer.get("curie")
print(computer.list_published_ports())
computer.unpublish_port(8000)

CLI Commands

Most computer commands support --json, which prints structured data for scripts and automation:

celesto computer list --json
celesto computer templates --json
celesto computer create --disk-size-mb 15360 --json

celesto computer ssh is interactive and does not support JSON output.

Other Python SDK APIs

The high-level SDK now exposes computers directly through Computer. Deployment and Gatekeeper helpers are still available from the CLI while their direct SDK resource APIs are being updated to match this style.

OpenAI Agents SDK Sandboxes

OpenAI agents can use Celesto as their working computer. This lets the agent read files, run commands, and create artifacts in a separate place.

A sandbox is a separate computer where an agent can work. A session is one running connection to that computer.

Install the optional dependencies:

pip install "celesto[openai-agents]"

Set both API keys before running the example. Celesto uses CELESTO_API_KEY to create the computer. The OpenAI Agents SDK uses OPENAI_API_KEY to run the agent.

export CELESTO_API_KEY="your-celesto-api-key"
export OPENAI_API_KEY="your-openai-api-key"

Then create a sandbox session for the agent:

import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from celesto.integrations.openai_agents import CelestoSandboxClient


async def main() -> None:
    agent = SandboxAgent(
        name="Workspace analyst",
        instructions="Inspect the sandbox workspace before answering.",
    )

    client = CelestoSandboxClient()
    session = await client.create()

    try:
        async with session:
            result = await Runner.run(
                agent,
                "Run `uname -a` in the sandbox and summarize the result.",
                run_config=RunConfig(sandbox=SandboxRunConfig(session=session)),
            )
            print(result.final_output)
    finally:
        await client.delete(session)


asyncio.run(main())

If your agent needs common coding tools preinstalled, pass options=CelestoSandboxClientOptions(template_id="coding-agent") when you call client.create(). Import CelestoSandboxClientOptions from celesto.integrations.openai_agents.

For local sandbox runs, use SmolVMSandboxClient and SmolVMSandboxClientOptions from celesto.integrations.openai_agents. SmolVM is a local tool for running a separate sandbox on your own machine.

Handle Errors in Python

Catch Celesto exceptions when your app needs custom recovery behavior.

from celesto.sdk.exceptions import (
    CelestoAuthenticationError,
    CelestoNetworkError,
    CelestoNotFoundError,
    CelestoRateLimitError,
    CelestoServerError,
    CelestoValidationError,
)

CelestoRateLimitError includes a retry_after value when the API sends one.

Develop Locally

If you are contributing and have uv installed, run these commands from the repository root:

uv sync
uv run pytest
uv run ruff check .
uv run ruff format .

Links

• Documentation
• Celesto Platform
• GitHub Repository

License

Apache License 2.0