celesto 0.0.5

Python SDK and CLI for the Celesto AI platform.

Celesto

Celesto gives AI agents their own isolated computer. Your agent can run commands, create files, and use tools without touching your machine.

pip install celesto        # Python SDK + CLI
npm install @celestoai/sdk # JavaScript/TypeScript SDK

Quick Start

Python:

from celesto import Celesto

client = Celesto()

computer = client.computers.create(template_id="coding-agent")
print(f"Computer ready: {computer['name']}")

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

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

JavaScript / TypeScript:

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

const celesto = new Celesto({ token: process.env.CELESTO_API_KEY });

const computer = await celesto.computers.create({ templateId: "coding-agent" });
console.log(`Computer ready: ${computer.name}`);

const result = await celesto.computers.exec(computer.id, "uname -a");
console.log(result.stdout);

await celesto.computers.delete(computer.id);

CLI:

export CELESTO_API_KEY="your-api-key"

celesto computer create --template coding-agent
celesto computer run einstein "ls -la"
celesto computer ssh einstein       # interactive shell
celesto computer delete einstein

Why Celesto?

• Fast -- computers boot in seconds
• Isolated -- each computer is separated from your machine
• Simple -- three API calls: create, exec, delete
• Built for agents -- give your AI a computer it can safely use

Installation

pip install celesto

Requires Python 3.10+.

Authentication

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

For CLI commands, save it once:

celesto auth login

The CLI stores the key in your operating system's secure credential store and uses it for future commands.

export CELESTO_API_KEY="your-api-key"

Or pass it directly:

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

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 an isolated place.

OpenAI calls this a SandboxAgent: an agent that has a separate computer for its work. Celesto supports two options:

• Hosted Celesto computers for cloud runs.
• Local SmolVM sandboxes for work on your own machine.

pip install "celesto[openai-agents]"  

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

agent = SandboxAgent(
    name="Workspace analyst",
    instructions="Inspect the sandbox workspace before answering.",
)

client = CelestoSandboxClient()
session = await client.create(
    options=CelestoSandboxClientOptions(template_id="coding-agent")
)
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)

Use SmolVMSandboxClient and SmolVMSandboxClientOptions from the same module when you want the same agent flow to run on a local SmolVM sandbox.

Computers API

Templates are ready-made computer setups. Choose one when you want a computer that already has the tools your agent needs.

Create

computer = client.computers.create(
    template_id="coding-agent",
    cpus=2,
    memory=2048,
    disk_size_mb=15360,
)
print(computer["name"])  # e.g., "einstein"

Omit CPU, memory, or disk fields to use the selected template defaults.

templates = client.computers.list_templates()
for template in templates:
    print(template["id"], template["default_ram_mb"])

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 auth login	Save your API key
celesto auth status	Check whether an API key is saved
celesto auth logout	Remove your saved API key
celesto computer create [--template ID] [--cpus N] [--memory MB] [--disk-size-mb MB]	Create a computer
celesto computer templates	List computer templates
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 templates --json
celesto computer create --template coding-agent --disk-size-mb 15360 --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
• JS/TS SDK docs
• Platform
• GitHub

License

Apache License 2.0