Create and manage sandboxed computers

The Computers API gives your code or agent an isolated Linux computer. You create a computer, run work inside it, and then stop, start, or delete it when your workflow is done.

Computer lifecycle

Create

Create a new computer from scratch or a template such as coding-agent.

Run

Execute shell commands, inspect output, and publish ports when a service needs a public URL.

Manage

Get details, list computers, stop and start long-lived computers, or delete temporary computers.

Celesto accepts Nano (1 vCPU, 512 MB), Small (1 vCPU, 1 GB), Standard (2 vCPU, 4 GB), and Large (4 vCPU, 12 GB). Free and Nano plans can create Nano computers. Builder and Growth can create every named size. See Choose computer size.

Create a computer

Use Computer() with no arguments to get a fresh scratch computer, which is a minimal Ubuntu sandbox.

create_computer.py

from celesto import Computer


computer = Computer()
print(computer.name)
print(computer.id)
print(computer.status)

computer.delete()

Override CPU, memory, or disk size when the default size is too small:

create_sized_computer.py

from celesto import Computer


computer = Computer(cpus=2, memory=4096, disk="15gb")
print(f"{computer.name} has {computer.vcpus} vCPUs")
print(f"{computer.ram_mb} MB RAM")

computer.delete()

integer

CPU value from a named size. Use together with the matching memory value. Defaults to the template’s value.

integer

Memory in MB from a named size. Use together with the matching cpus value. Defaults to the template’s value.

integer | string

Disk size as MB or a string such as "15gb". Alias for disk_size_mb.

integer

Disk size in MB. Range: 512-20480. Defaults to the template’s value.

string

default:"scratch"

Sandbox template ID. Pass coding-agent when your agent needs common coding tools already installed.

string

Optional immutable template version. Pin this when you want repeatable builds as a template changes over time.

Use a template

A template is a ready-made computer image with extra tools and default CPU, memory, and disk settings. Use coding-agent for common coding workflows:

create_from_template.py

from celesto import Computer


computer = Computer(template_id="coding-agent")
result = computer.run("python3 --version")
print(result["stdout"].strip())

computer.delete()

List templates

list_templates.py

from celesto import Computer


templates = Computer.list_templates()
for template in templates:
    print(
        f"{template['id']}: {template['display_name']} "
        f"({template['default_vcpus']} vCPU, {template['default_ram_mb']} MB RAM)"
    )

Run commands

run_command.py

from celesto import Computer


computer = Computer(template_id="scratch")
result = computer.run("ls -la /home", timeout=60)
print(result["stdout"])
print(result["exit_code"])

computer.delete()

integer

required

Exit code of the command. 0 means success.

string

required

Standard output from the command.

string

required

Standard error output from the command.

Stream command output

Use run_stream() when you want to see output as it is produced instead of waiting for the command to finish. It returns an iterator of event dicts that arrive over a server-sent events stream, which is useful for long-running builds, test suites, or agent tool calls that print progress.

stream_command.py

from celesto import Computer


computer = Computer(template_id="coding-agent")

for event in computer.run_stream("pytest -q", timeout=300):
    if event["type"] in ("stdout", "stderr"):
        print(event["data"], end="")
    elif event["type"] == "exit":
        print(f"\nexit code: {event['exit_code']}")

computer.delete()

Each event has a type field:

started — the command has been accepted. Includes command_id and timeout_seconds.
stdout and stderr — a chunk of output. The bytes are in data.
exit — the command finished. Includes exit_code, duration_ms, and timed_out.

The stream always ends with an exit event, even when the command times out or is interrupted. Break out of the loop early to stop consuming; the remote command still runs to completion.

Get and list computers

list_computers.py

from celesto import Computer


computers = Computer.list(status="running")
for computer in computers:
    info = Computer.get(computer["id"])
    print(f"{info.name}: {info.status}")

print(f"Total: {len(computers)}")

Publish a port

Publishing a port gives your computer a public HTTPS URL. Use it when an app, API server, or notebook running inside the computer needs to be reachable from outside the sandbox.

publish_port.py

from celesto import Computer


computer = Computer(template_id="coding-agent")
computer.run("cd /tmp && python3 -m http.server 8000 > /tmp/server.log 2>&1 &")

url = computer.publish_port(8000)
print(url)

for port in computer.list_published_ports():
    print(f"{port['port']} -> {port['url']} ({port['status']})")

computer.unpublish_port(8000)
computer.delete()

Open a terminal connection

Use create_terminal_session() when your application needs an interactive shell against a running computer, for example to power a web terminal in your own product. It calls POST /computers/{id}/terminals and returns a short-lived, direct connection to Celesto’s fast terminal gateway. Your account must have write access to the computer.

terminal.py

import websockets
import asyncio
from celesto import Computer


async def main():
    computer = Computer.get("einstein")
    session = computer.create_terminal_session()

    async with websockets.connect(session["url"]) as ws:
        await ws.send("echo hello\n")
        print(await ws.recv())


asyncio.run(main())

session["url"] embeds a short-lived terminal token. Treat it as a secret: pass it straight to your WebSocket client, do not log it, and do not send it to a browser you do not control. Use session["expires_at"] to know when to request a new session.

string

required

Durable terminal session ID.

string

required

Base gateway URL without credentials. Combine with token yourself only when you cannot use url directly.

string

required

Short-lived terminal token. Treat this as a secret.

string

required

ISO 8601 timestamp after which the token stops working. Create a new session before this time.

string

required

Authenticated wss:// URL ready to pass to a WebSocket client.

Stop, start, and delete

lifecycle.py

from celesto import Computer


computer = Computer()
computer.stop()
computer.start()
computer.delete()

Computer response fields

string

required

Unique identifier for the computer, such as cmp_abc123.

string

required

Auto-generated display name for the computer, such as einstein.

string

required

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

integer

required

Number of virtual CPUs allocated.

integer

required

Memory allocated in MB. TypeScript exposes this as ramMb.

integer

required

Disk allocated in MB. TypeScript exposes this as diskSizeMb.

string

required

Sandbox template the computer was created from. TypeScript exposes this as templateId.

string

Pinned template version, if one was provided at create time. TypeScript exposes this as templateVersion.

object

Connection details for accessing a running computer.

Show Connection properties

string

SSH connection string for terminal access.

string

URL for browser-based access to the computer.

Start Here

Features

Guides

Agents and Integrations

Create and manage sandboxed computers

Computer lifecycle

Create a computer

Use a template

List templates

Run commands

Stream command output

Get and list computers

Publish a port

Open a terminal connection

Stop, start, and delete

Computer response fields

​Computer lifecycle

​Create a computer

​Use a template

​List templates

​Run commands

​Stream command output

​Get and list computers

​Publish a port

​Open a terminal connection

​Stop, start, and delete

​Computer response fields

Computer lifecycle

Create a computer

Use a template

List templates

Run commands

Stream command output

Get and list computers

Publish a port

Open a terminal connection

Stop, start, and delete

Computer response fields