Celesto SDK - Celesto AI

The Celesto SDK lets you create sandboxed computers, run commands inside them, and manage the full lifecycle from your code or the command line. You can use it to spin up isolated environments for AI agents, run untrusted code safely, or automate development workflows. The SDK is available for both Python and JavaScript/TypeScript.

Installation

pip install celesto

Authentication

Set your API key as an environment variable or pass it directly:

import os
os.environ["CELESTO_API_KEY"] = "your-api-key"

You can also pass the key when you create the client:

from celesto import Celesto

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

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

Quick example

from celesto import Celesto

with Celesto() 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"])

Computers API

The Computers API lets you create, manage, and interact with sandboxed virtual machines.

Create a computer

computer = client.computers.create(cpus=2, memory=2048)
print(computer["name"])   # e.g., "einstein"
print(computer["id"])     # e.g., "cmp_abc123"
print(computer["status"]) # "creating" or "running"

cpus

integer

default:"1"

Number of virtual CPUs. Range: 1-16.

memory

integer

default:"1024"

Memory in MB. Range: 512-32768.

image

string

default:"ubuntu-desktop-24.04"

OS image to use for the computer.

The response includes these fields:

string

required

Unique identifier for the computer (e.g., cmp_abc123).

name

string

required

Auto-generated display name for the computer (e.g., einstein).

status

string

required

Current status. One of: creating, running, stopping, stopped, starting, deleting, deleted, error.

vcpus

integer

required

Number of virtual CPUs allocated.

ram_mb

integer

required

Memory allocated in MB.

image

string

required

OS image used.

created_at

string

required

ISO 8601 timestamp of when the computer was created.

stopped_at

string

ISO 8601 timestamp of when the computer was stopped. Only present if the computer has been stopped.

last_error

string

Description of the most recent error, if the computer is in error status.

connection

object

Connection details for accessing a running computer.

Show Connection properties

ssh

string

SSH connection string for terminal access.

access_url

string

URL for browser-based access to the computer.

Execute commands

Run a shell command on a computer:

result = client.computers.exec(computer["id"], "ls -la /home")
print(result["stdout"])
print(result["exit_code"])

computer_id

string

required

Computer ID or name.

command

string

required

Shell command to execute.

timeout

integer

default:"30"

Timeout in seconds. Range: 1-300.

The response includes:

exit_code

integer

required

Exit code of the command. 0 means success.

stdout

string

required

Standard output from the command.

stderr

string

required

Standard error output from the command.

Get a computer

Retrieve details of a specific computer:

info = client.computers.get(computer["id"])
print(f"{info['name']}: {info['status']}")

List computers

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

The response includes:

computers

array

required

List of computer objects, each with the same fields as the create response.

count

integer

required

Total number of computers in the list.

Lifecycle

Stop, start, and delete computers as needed:

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

Terminal connection (JavaScript only)

The JavaScript SDK provides a getTerminalConnection method that returns the URL, headers, and first message you need to open an interactive WebSocket terminal session. Bring your own WebSocket library — the SDK has zero runtime dependencies, so you can use ws, Node’s built-in WebSocket (Node 22+), or any other client.

import WebSocket from "ws";

const conn = await client.computers.getTerminalConnection("my-computer");
const ws = new WebSocket(conn.url, { headers: conn.headers });
ws.on("open", () => ws.send(conn.firstMessage));
ws.on("message", (data) => process.stdout.write(data));

The method accepts either a computer ID (e.g., cmp_abc123) or a human-readable name. It resolves the name to the canonical ID before the handshake.

url

string

required

The wss:// URL for the WebSocket connection.

headers

object

required

Headers to include in the WebSocket handshake, including the Authorization header.

firstMessage

string

required

JSON string to send as the first message after connecting.

CLI reference

The celesto CLI focuses on computer management. All commands live under celesto computer.

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 (auto-resumes stopped computers)
`celesto computer ssh <name>`	Interactive terminal (auto-resumes stopped computers)
`celesto computer stop <name>`	Stop a computer
`celesto computer start <name>`	Start a stopped computer
`celesto computer delete <name> [--force]`	Delete a computer

You can use either the computer name or ID for any command that takes a computer identifier.

Auto-resume

The run and ssh commands automatically resume a stopped computer before executing. If you run a command or open a terminal session on a stopped computer, the CLI starts it, waits for it to become available, and then proceeds. You do not need to call start manually first.

# This works even if "einstein" is stopped
celesto computer run einstein "uname -a"

# Opens a terminal, resuming the computer if needed
celesto computer ssh einstein

JSON output

All commands support --json (-j) for machine-readable output, which is useful for scripting and AI agent integrations:

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

Examples

Create a computer and run a command:

export CELESTO_API_KEY="your-api-key"

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

Deployment API

The Deployment API lets you package and deploy AI agents to Celesto’s managed infrastructure.

Deploy an agent

The Deployment API is currently available in the Python SDK only.

from pathlib import Path

result = client.deployment.deploy(
    folder=Path("./my-agent"),
    name="weather-agent-v1",
    description="Weather assistant",
    envs={"OPENAI_API_KEY": "sk-..."}
)

print(f"Deployment ID: {result['id']}")
print(f"Status: {result['status']}")

folder

Path

required

Path to the directory containing your agent code.

name

string

required

Unique name for the deployment.

description

string

Human-readable description of the deployment.

envs

object

Environment variables as key-value pairs.

project_name

string

Project name to scope the deployment. Defaults to your first project.

The response includes:

string

required

Unique deployment identifier.

status

string

required

Deployment status: BUILDING, READY, or FAILED.

url

string

Endpoint URL, available when status is READY.

message

string

Additional information about the deployment result.

List deployments

deployments = client.deployment.list()
for dep in deployments:
    print(f"{dep['name']}: {dep['status']}")

Each deployment object in the list includes:

string

required

Unique deployment identifier.

name

string

required

Deployment name.

description

string

Human-readable description, if provided during deploy.

status

string

required

Deployment status: READY, BUILDING, FAILED, or STOPPED.

created_at

string

ISO 8601 timestamp of when the deployment was created.

updated_at

string

ISO 8601 timestamp of the most recent update.

Error handling

Both SDKs provide typed errors so you can handle different failure modes.

Python
JavaScript

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

Exception	When it occurs
`CelestoAuthenticationError`	Invalid or missing API key (401/403)
`CelestoValidationError`	Invalid parameters (400/422)
`CelestoNotFoundError`	Resource not found (404)
`CelestoRateLimitError`	Too many requests (429)
`CelestoServerError`	Server-side error (5xx)
`CelestoNetworkError`	Connection failures or timeouts

import { CelestoError, CelestoApiError, CelestoNetworkError } from "@celestoai/sdk";

try {
  await client.computers.get("missing-name");
} catch (err) {
  if (err instanceof CelestoApiError) {
    console.error(`API ${err.status}:`, err.data);
  } else if (err instanceof CelestoNetworkError) {
    console.error("Network error:", err.cause);
  } else if (err instanceof CelestoError) {
    console.error("SDK error:", err.message);
  }
}

Error class	Extends	When it occurs
`CelestoApiError`	`CelestoError`	Any non-2xx HTTP response. Inspect `.status` (HTTP code), `.data` (parsed body), and `.requestId`.
`CelestoNetworkError`	`CelestoError`	DNS failures, timeouts, or connection errors. Inspect `.cause` for the underlying `Error`.
`CelestoError`	`Error`	Base class. Catch this to handle any SDK error.

Network failures from fetch() (DNS, offline, timeout) are wrapped as CelestoNetworkError instead of leaking raw TypeError. Catch CelestoError to handle both API and network errors with one branch.

Celesto Platform

Documentation Index

​Installation

​Authentication

​Quick example

​Computers API

​Create a computer

​Execute commands

​Get a computer

​List computers

​Lifecycle

​Terminal connection (JavaScript only)

​CLI reference

​Auto-resume

​JSON output

​Examples

​Deployment API

​Deploy an agent

​List deployments

​Error handling

Installation

Authentication

Quick example

Computers API

Create a computer

Execute commands

Get a computer

List computers

Lifecycle

Terminal connection (JavaScript only)

CLI reference

Auto-resume

JSON output

Examples

Deployment API

Deploy an agent

List deployments

Error handling