> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Celesto SDK for sandboxed computers and agents

> Use the Celesto SDK to create sandboxed computers, run shell commands, publish ports, and deploy AI agents from either Python or JavaScript clients.

The Celesto SDK lets you create a safe computer for your code or agent, run work inside it, and clean it up when you are done. You can use Celesto from Python, TypeScript, JavaScript, or the `celesto` command line tool.

Use this section when you want to:

* Run generated code in an isolated computer.
* Give an AI agent a workspace with files, shell commands, and optional public ports.
* Keep long-running agent work in a durable cloud workspace.
* Connect end-user data sources through Gatekeeper from TypeScript apps.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/celesto-sdk/quickstart">
    Install the SDK, create your first computer, run a command, and delete it.
  </Card>

  <Card title="Authentication" icon="key" href="/celesto-sdk/authentication">
    Save your API key for the CLI or pass it to the SDK from your environment.
  </Card>

  <Card title="Sandboxed computers" icon="server" href="/celesto-sdk/computers">
    Create computers, use templates, run commands, manage ports, and control lifecycle.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/celesto-sdk/cli">
    Use `celesto auth` and `celesto computer` commands from your terminal.
  </Card>

  <Card title="Deployments" icon="cloud-upload" href="/celesto-sdk/deployments">
    See the current status of managed deployment APIs.
  </Card>

  <Card title="Pi coding agent" icon="terminal" href="/celesto-sdk/guides/pi-coding-agent">
    Keep Pi local while its coding tools run on an isolated Celesto cloud computer.
  </Card>

  <Card title="OpenAI Agents" icon="robot" href="/celesto-sdk/openai-agents">
    Give an OpenAI `SandboxAgent` a hosted Celesto computer or local SmolVM.
  </Card>

  <Card title="Gatekeeper" icon="shield-check" href="/celesto-sdk/gatekeeper">
    Connect your users to providers like Google Drive from TypeScript apps.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/celesto-sdk/errors">
    Handle authentication, validation, rate limit, server, and network errors.
  </Card>
</CardGroup>

## Feature guides

These guides cover the parts of Celesto computers that matter most when you move from a quickstart to real agent workflows.

<CardGroup cols={2}>
  <Card title="Publish ports" icon="globe" href="/celesto-sdk/features/publish-ports">
    Expose a server, preview app, notebook, or webhook receiver running inside a computer.
  </Card>

  <Card title="Computer sessions" icon="rotate-cw" href="/celesto-sdk/features/lifecycle">
    Create, stop, start, resume, and delete computers for temporary or long-lived work.
  </Card>

  <Card title="Computer resources" icon="cpu" href="/celesto-sdk/features/resources">
    Choose CPU, memory, disk size, and templates for heavier agent workloads.
  </Card>

  <Card title="Persistent state" icon="hard-drive" href="/celesto-sdk/features/persistence">
    Keep files, installed packages, and agent workspace state between sessions.
  </Card>
</CardGroup>

## Choose your SDK

Pages with SDK examples use Mintlify's `View` component. Pick Python or TypeScript from the selector at the top of the page, and the examples and table of contents update for that language.

<View title="Python" icon="python">
  Use the Python SDK when you are building agents, automation scripts, or backend services in Python. Python examples use `snake_case` parameters such as `template_id` and `disk_size_mb`.

  ```bash theme={null}
  pip install -U celesto
  ```

  Start with the [Python quickstart](/celesto-sdk/quickstart), then read [Sandboxed computers](/celesto-sdk/computers) when you need templates, command execution, ports, or lifecycle control.
</View>

<View title="TypeScript" icon="js">
  Use the npm SDK when you are building Node.js services, TypeScript workers, or web tooling. TypeScript and JavaScript projects use the same package. TypeScript examples use `camelCase` parameters such as `templateId` and `diskSizeMb`.

  ```bash theme={null}
  npm install @celestoai/sdk@latest
  ```

  Start with the [TypeScript quickstart](/celesto-sdk/quickstart), then read [Sandboxed computers](/celesto-sdk/computers) when you need templates, command execution, lifecycle control, or terminal connections.
</View>

## How the SDK fits together

<Steps>
  <Step title="Authenticate">
    Create an API key in Celesto, then save it once with the CLI or set `CELESTO_API_KEY` for SDK code.

    <Check>
      Your SDK client and CLI commands can call the Celesto API.
    </Check>
  </Step>

  <Step title="Create a computer">
    Start with the default `scratch` computer, or use the `coding-agent` template when your agent needs common coding tools.

    <Check>
      You have an isolated Linux computer with an ID and a status.
    </Check>
  </Step>

  <Step title="Run work">
    Execute shell commands, inspect output, publish a supported port, or connect a terminal.

    <Check>
      Your code or agent runs inside the sandbox instead of on your host machine.
    </Check>
  </Step>

  <Step title="Clean up">
    Delete temporary computers when you are done, or stop long-lived computers when you want to keep their files for later.
  </Step>
</Steps>