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

# Use the Celesto HTTP API and TypeScript SDK

> Run the local Celesto HTTP server to create sandboxes and run commands over REST, then control those sandboxes from TypeScript with the generated client.

Celesto can run a local HTTP server so another process can create sandboxes and run commands without importing Python. This is useful for web apps, local tools, TypeScript services, and agent runtimes that already speak HTTP.

## When to use the HTTP API

Use the HTTP API when:

* A JavaScript or TypeScript process needs to create and control sandboxes.
* A local service needs a stable REST interface instead of Python objects.
* You want to generate clients from the OpenAPI spec.
* You want to keep one Celesto server process alive while several tools make requests.

For Python-only workflows, the [`Celesto` class](https://celesto.ai/docs/celesto/api/celesto) is still the shortest path.

## Start the server

Install the web dependencies:

```bash theme={null}
pip install "celesto[dashboard]"
```

Start the local server:

```bash theme={null}
celesto server start --host 127.0.0.1 --port 8000
```

You should see:

```text theme={null}
Celesto HTTP API listening on http://127.0.0.1:8000
OpenAPI spec: http://127.0.0.1:8000/openapi.json
```

> [!WARNING]
>
> Keep the server bound to `127.0.0.1` unless you have added your own network controls. The local API can create sandboxes and run commands on your machine.

## Core endpoints

| Method | Path | What it does |
| - | - | - |
| `POST` | `/sandboxes` | Create, boot, and register a sandbox |
| `GET` | `/sandboxes` | List sandboxes on the host |
| `GET` | `/sandboxes/{id}` | Get one sandbox's state |
| `POST` | `/sandboxes/{id}/exec` | Run a command inside a sandbox |
| `GET` | `/sandboxes/{id}/desktop` | Get the sandbox's desktop connection details |
| `DELETE` | `/sandboxes/{id}` | Stop and delete a sandbox |

## Create a sandbox with curl

```bash theme={null}
curl -s -X POST http://127.0.0.1:8000/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"os":"ubuntu","memory":512,"disk_size":1024}'
```

Example response:

```json theme={null}
{
  "id": "vm-a1b2c3d4",
  "status": "running"
}
```

The request body mirrors the auto-config options of the Python `Celesto(...)` constructor.

**os** `"alpine" | "ubuntu" | "windows"`

Guest operating system. Omit it for the default Linux sandbox.

**image** `string`

Image reference to boot, such as an S3 image URI, `file://` URI, or local Windows `qcow2` path.

**memory** `integer`

Guest memory in MiB.

**disk\_size** `integer`

Guest disk size in MiB.

**backend** `"firecracker" | "qemu" | "libkrun"`

Runtime backend override.

## Run a command

```bash theme={null}
curl -s -X POST http://127.0.0.1:8000/sandboxes/vm-a1b2c3d4/exec \
  -H "Content-Type: application/json" \
  -d '{"command":"python3 --version","timeout":30,"shell":"login"}'
```

Example response:

```json theme={null}
{
  "exit_code": 0,
  "stdout": "Python 3.12.3\n",
  "stderr": ""
}
```

**command** `string` *required*

Command to run inside the sandbox.

**timeout** `integer` (default: 30)

Maximum seconds to wait for the command.

**shell** `"login" | "raw"` (default: login)

Use `login` for the guest login shell, or `raw` to run the command without shell wrapping.

## Use the TypeScript client

The Celesto repository includes a generated TypeScript client and a small wrapper class named `Celesto`. In a project where that TypeScript package is available, point it at the local server:

```typescript celesto-client.ts theme={null}
import { Celesto } from "@celestoai/celesto";

const celesto = new Celesto({
  baseUrl: "http://127.0.0.1:8000",
});

const sandbox = await celesto.sandbox.create({
  os: "ubuntu",
  memory: 512,
  disk_size: 1024,
});

const result = await celesto.sandbox.exec(sandbox.id, {
  command: "uname -a",
  timeout: 30,
  shell: "login",
});

console.log(result.stdout);

await celesto.sandbox.delete(sandbox.id);
```

The wrapper groups operations under `celesto.sandbox`:

| Method | HTTP call |
| - | - |
| `celesto.sandbox.create(...)` | `POST /sandboxes` |
| `celesto.sandbox.list()` | `GET /sandboxes` |
| `celesto.sandbox.get(id)` | `GET /sandboxes/{id}` |
| `celesto.sandbox.exec(id, body)` | `POST /sandboxes/{id}/exec` |
| `celesto.sandbox.desktop(id)` | `GET /sandboxes/{id}/desktop` |
| `celesto.sandbox.delete(id)` | `DELETE /sandboxes/{id}` |

## Get sandbox desktop connection details

Use `sandbox.desktop(id)` to get the details you need to open a sandbox's desktop viewer from a Node or TypeScript app. This is the SDK equivalent of the [`celesto sandbox desktop`](https://celesto.ai/docs/celesto/guides/macos-sandboxes) CLI command, so you can wire the same workflow into a service or agent instead of shelling out.

```typescript sandbox-desktop.ts theme={null}
import { Celesto } from "@celestoai/celesto";

const celesto = new Celesto({
  baseUrl: "http://127.0.0.1:8000",
});

const desktop = await celesto.sandbox.desktop("vm-a1b2c3d4");

console.log(desktop.protocol);   // "vnc"
console.log(desktop.host);       // "127.0.0.1"
console.log(desktop.port);       // e.g. 5900
console.log(desktop.viewer_url); // URL to open in a desktop viewer
```

The returned `DesktopResponse` has:

* `protocol` — the desktop protocol, currently `"vnc"`.
* `host` — the loopback host the desktop is bound to.
* `port` — the port the desktop is listening on.
* `viewer_url` — a URL you can hand to a desktop viewer to open the session.

Point your viewer at `viewer_url`, or build your own connection from `host` and `port`. The method throws if the sandbox has no desktop or the server rejects the request.

> [!NOTE]
>
> The docs intentionally avoid an npm install command here. The release source includes the `ts/` package and generated client, but package publication should be verified before documenting a registry install path.

## Generate clients from OpenAPI

The server publishes its OpenAPI spec at:

```text theme={null}
http://127.0.0.1:8000/openapi.json
```

Use that URL with your client generator of choice when you need another language or a custom TypeScript client.

## Troubleshooting

> [accordion] The server says dashboard dependencies are missing
>
> Install the web extra, then start the server again:
>
> ```bash theme={null}
> pip install "celesto[dashboard]"
> celesto server start --host 127.0.0.1 --port 8000
> ```

> [accordion] The port is already in use
>
> Pick another port:
>
> ```bash theme={null}
> celesto server start --port 8001
> ```

> [accordion] A command exits non-zero
>
> A command that runs and returns a non-zero exit code still produces a successful HTTP response. Check `exit_code`, `stdout`, and `stderr` in the response body.

## Related

> [card] [celesto server](https://celesto.ai/docs/celesto/cli/server.md)
>
> CLI reference for the local API server

> [card] [Celesto Python API](https://celesto.ai/docs/celesto/api/celesto.md)
>
> Use Celesto directly from Python


## Related topics

- [celesto server](https://celesto.ai/docs/celesto/cli/server.md)
- [Connect users to third-party OAuth with Gatekeeper](https://celesto.ai/docs/cloud/gatekeeper.md)
- [Celesto SDK for sandboxed computers and agents](https://celesto.ai/docs/cloud/overview.md)
- [CLI overview](https://celesto.ai/docs/celesto/cli/overview.md)
- [Authenticate the Celesto SDK and CLI](https://celesto.ai/docs/cloud/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.