> ## 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.

# celesto server

> Use celesto server start to run the local Celesto HTTP API for scripts, service integrations, and the TypeScript SDK.

`celesto server start` runs a local HTTP API that can create sandboxes, list them, delete them, and run commands inside them. Use it when another process needs to control Celesto without importing the Python SDK.

## Install dependencies

The server uses the same web dependencies as the dashboard:

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

## Synopsis

```bash theme={null}
celesto server start [OPTIONS]
```

## Options

**--host** `string` (default: 127.0.0.1)

Address to bind.

**--port** `integer` (default: 8000)

Port to bind. Must be between `1` and `65535`.

## Start the server

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

The command prints the API URL and OpenAPI spec URL:

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

## Available endpoints

| Method | Path | What it does |
| - | - | - |
| `POST` | `/sandboxes` | Create and start 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 |
| `DELETE` | `/sandboxes/{id}` | Delete a sandbox |

## Try it with curl

These examples use `jq` to read the sandbox ID from the JSON response.

```bash theme={null}
curl -s http://127.0.0.1:8000/sandboxes
```

Create a sandbox and save the generated ID:

```bash theme={null}
sandbox_id="$(
  curl -s -X POST http://127.0.0.1:8000/sandboxes \
    -H "Content-Type: application/json" \
    -d '{"os":"ubuntu","memory":512}' \
    | jq -r '.id'
)"

echo "$sandbox_id"
```

Run a command in that sandbox:

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

## Related

* [HTTP API and TypeScript SDK](https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk.md) - Build against the API
* [`celesto ui`](https://celesto.ai/docs/celesto/cli/ui) - Start the dashboard
* [`celesto sandbox create`](https://celesto.ai/docs/celesto/cli/create) - Create sandboxes from the CLI


## Related topics

- [celesto ui](https://celesto.ai/docs/celesto/cli/ui.md)
- [Use the Celesto HTTP API and TypeScript SDK](https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk.md)
- [Give your AI assistant a cloud computer](https://celesto.ai/docs/cloud/mcp-server.md)
- [CLI overview](https://celesto.ai/docs/celesto/cli/overview.md)
- [Windows sandboxes in Celesto](https://celesto.ai/docs/celesto/guides/windows-guests.md)


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