celesto 0.0.3

Python SDK and CLI for the Celesto AI platform.

Celesto

Sandboxed cloud computers for AI agents. Spin up isolated computers in seconds, run workflows/commands or long running agents -- all from Python or the CLI.

pip install celesto

Quick Start

from celesto.sdk import CelestoSDK

with CelestoSDK() as client:
    computer = client.computers.create(cpus=2, memory=2048)
    print(f"Computer ready: {computer['name']}")

    result = client.computers.exec(computer["id"], "uname -a")
    print(result["stdout"])

    client.computers.delete(computer["id"])

Or from the command line:

export CELESTO_API_KEY="your-api-key"

celesto computer create --cpus 2 --memory 2048
celesto computer run einstein "ls -la"
celesto computer ssh einstein       # interactive shell
celesto computer delete einstein

Why Celesto?

• Fast -- computers boot in seconds via Firecracker microVMs
• Isolated -- every sandbox is a real VM, not a container
• Simple -- three API calls: create, exec, delete
• Built for agents -- give your AI full computer access without risking your host

Installation

pip install celesto

Requires Python 3.10+.

Authentication

Get your API key from celesto.ai under Settings > Security.

export CELESTO_API_KEY="your-api-key"

Or pass it directly:

client = CelestoSDK(api_key="your-api-key")

Computers API

Create

computer = client.computers.create(cpus=2, memory=2048)
print(computer["name"])  # e.g., "einstein"

Execute commands

result = client.computers.exec(computer["id"], "apt-get update && apt-get install -y curl")
print(result["stdout"])
print(result["exit_code"])

Lifecycle

client.computers.stop(computer_id)
client.computers.start(computer_id)
client.computers.delete(computer_id)

List

result = client.computers.list()
for vm in result["computers"]:
    print(f"{vm['name']}: {vm['status']}")

CLI

Command	Description
celesto computer create [--cpus N] [--memory MB]	Create a computer
celesto computer list	List all computers
celesto computer run <name> "command"	Execute a command
celesto computer ssh <name>	Interactive shell
celesto computer stop <name>	Stop a computer
celesto computer start <name>	Start a stopped computer
celesto computer delete <name> [--force]	Delete a computer

JSON output

All commands support --json for machine-readable output:

celesto computer list --json
celesto computer create --cpus 2 --memory 2048 --json
celesto computer run einstein "uname -a" --json

Error Handling

from celesto.sdk.exceptions import (
    CelestoAuthenticationError,  # 401/403
    CelestoNotFoundError,        # 404
    CelestoValidationError,      # 400/422
    CelestoRateLimitError,       # 429 -- has retry_after attribute
    CelestoServerError,          # 5xx
    CelestoNetworkError,         # connection failures
)

Links

• Documentation
• Platform
• GitHub

License

Apache License 2.0