# Celesto Sandboxes

> Cloud Linux sandboxes for AI agents. Each one is its own virtual machine with a terminal, a desktop view, a browser your code can drive, public preview URLs, and a disk that survives stops.

- Page: https://celesto.ai/sandboxes
- Docs: https://celesto.ai/docs/cloud/quickstart
- MCP server: https://mcp.celesto.ai/mcp
- Open source (Apache-2.0): https://github.com/CelestoAI/celesto
- Pricing: https://celesto.ai/pricing

## Quickstart

In the SDK and CLI a sandbox is called a computer (`Computer`, `celesto computer …`).

1. Authenticate: run `celesto auth login`, or create an API key in the Celesto console under Settings → Security and set `CELESTO_API_KEY`. The TypeScript SDK reads only `CELESTO_API_KEY` or an `apiKey` option.
2. Python (`pip install -U celesto`). `Computer()` runs locally by default, so pass `provider="cloud"`. Use `lifetime="persistent"` to keep the sandbox after your script exits:

```python
from celesto import Computer

computer = Computer(provider="cloud", lifetime="persistent", template_id="coding-agent")
print(computer.run("git --version", timeout=60).stdout)
computer.stop()  # keeps the disk; computer.start() resumes
```

3. TypeScript (`npm i @celestoai/sdk`): `const computer = await Computer.create({ templateId: "coding-agent" })`, then `(await computer.run("git --version")).stdout`.
4. CLI: every cloud command takes `--cloud`. `celesto computer create --cloud --name my-box`, then `celesto computer exec my-box --cloud -- git --version` or `celesto computer ssh my-box --cloud`. Add `--json` for machine-readable output.
5. `run()` waits 30 seconds by default; pass `timeout` (up to 300 seconds) or use `run_stream()` for long commands.
6. Desktop view (`computer.display()`) and the CDP browser (`computer.browser()`) need the `browser-agent` template.

## Features

### Get inside

- **Terminal in the browser**: Open a live shell on any running sandbox from the console. Use: `Console → Terminal`. Available in: Console.
- **Terminal from your laptop**: An interactive shell from your own terminal, with no SSH keys to manage. Use: `celesto computer ssh my-box --cloud`. Available in: CLI, SDK. Docs: https://celesto.ai/docs/cloud/cli
- **Desktop view**: Watch or take control of the sandbox's screen, live. On the browser templates. Use: `Console → Display · computer.display()`. Available in: Console, SDK. Docs: https://celesto.ai/docs/cloud/features/browser-and-display
- **Browser for agents**: A Chromium browser your code drives over CDP with Playwright or Puppeteer. Use: `computer.browser()`. Available in: SDK. Docs: https://celesto.ai/docs/cloud/features/browser-and-display

### Run code

- **Run any command**: Run a command and get its output and exit code. 30 seconds by default, up to 5 minutes with timeout. Use: `computer.run("npm test", timeout=300)`. Available in: CLI, SDK, MCP. Docs: https://celesto.ai/docs/cloud/computers
- **Streaming output**: Read stdout and stderr line by line while a long command runs. Use: `computer.run_stream("npm test")`. Available in: SDK. Docs: https://celesto.ai/docs/cloud/computers
- **Root access**: Full sudo on a real Linux machine. Install anything with apt, pip, or npm. Use: `sudo apt install …`. Available in: Console, CLI, SDK, MCP.
- **Docker support**: Run Docker containers inside your sandbox. Use: `docker run --rm hello-world`. Available in: Console, CLI, SDK, MCP.
- **Command history**: See every command a sandbox ran, with its exit code. Use: `Console → sandbox details`. Available in: Console, SDK.

### Share and connect

- **Public preview URLs**: Turn a port into an HTTPS link anyone can open. Up to 4 ports per sandbox. Use: `celesto computer port publish my-box --port 3000`. Available in: Console, CLI, SDK, MCP. Docs: https://celesto.ai/docs/cloud/features/publish-ports
- **Internet on or off**: Cut outbound internet for untrusted code with one option in the TypeScript SDK. Use: `networkPolicy: { mode: "off" }`. Available in: SDK. Docs: https://celesto.ai/docs/cloud/features/network-control

### Keep your work

- **Stop and start**: Stop a sandbox when you're done and start it later with files and installed packages intact. Use: `computer.stop() · computer.start()`. Available in: Console, CLI, SDK, MCP. Docs: https://celesto.ai/docs/cloud/features/lifecycle
- **Persistent disk and home**: The disk survives every stop. Stopped disks are kept for 30 days. Use: `Automatic`. Available in: Console, CLI, SDK, MCP. Docs: https://celesto.ai/docs/cloud/features/persistence
- **CelestoFS workspace**: Durable workspace storage that is not limited by the size of the sandbox's disk. Use: `Mounted automatically`. Available in: Console, CLI, SDK, MCP. Docs: https://celesto.ai/docs/cloud/features/petabyte-storage

### Pick the machine

- **Six sizes**: From 1 vCPU · 2 GB at $0.015/hour to 8 vCPU · 32 GB. Billed only while running. Use: `Computer(provider="cloud", vcpus=4, ram_mb=16384)`. Available in: Console, SDK.
- **Ready-made templates**: Start from a clean Ubuntu box, a coding-agent image with Git, Python, and Node, or a browser image. Use: `Computer(provider="cloud", template_id="coding-agent")`. Available in: Console, SDK. Docs: https://celesto.ai/docs/cloud/features/resources
- **Its own virtual machine**: Every sandbox is a separate KVM virtual machine, not a container sharing a kernel. Use: `Every sandbox`. Available in: Console, CLI, SDK, MCP.
- **Usage charts**: CPU, memory, and disk usage for each sandbox over the last hour or day. Use: `Console → sandbox details`. Available in: Console.

### Plug into your agents

- **MCP server**: Let Claude Code, Cursor, or any MCP client create sandboxes and run commands. Use: `claude mcp add --transport http celesto https://mcp.celesto.ai/mcp`. Available in: MCP. Docs: https://celesto.ai/docs/cloud/mcp-server
- **Python and TypeScript SDKs**: Create, run, and manage sandboxes from your own code. Use: `pip install -U celesto · npm i @celestoai/sdk`. Available in: SDK. Docs: https://celesto.ai/docs/cloud/quickstart
- **OpenAI Agents SDK**: Use a Celesto sandbox as the workspace for an OpenAI agent. Use: `CelestoSandboxClient`. Available in: SDK. Docs: https://celesto.ai/docs/cloud/openai-agents
- **Pi coding agent**: Run the Pi coding agent on a sandbox and sync your project to it. Use: `pi --celesto`. Available in: CLI. Docs: https://celesto.ai/docs/cloud/guides/pi-coding-agent
- **GitHub Actions runners**: Run your CI on Celesto sandboxes by changing one runs-on line. Use: `runs-on: celesto`. Available in: Console. Docs: https://celesto.ai/ci

## Sizes

- Micro: 1 vCPU, 2 GB RAM, 20 GB disk, $0.015 per running hour
- Small: 1 vCPU, 4 GB RAM, 25 GB disk, $0.020 per running hour
- Standard: 2 vCPU, 4 GB RAM, 30 GB disk, $0.030 per running hour
- Memory: 2 vCPU, 8 GB RAM, 40 GB disk, $0.040 per running hour
- Large: 4 vCPU, 16 GB RAM, 60 GB disk, $0.080 per running hour
- XL: 8 vCPU, 32 GB RAM, 100 GB disk, $0.160 per running hour

## Questions

### Can I run Docker in a Celesto sandbox?

Yes. Celesto sandboxes support Docker, so you can run containers inside your sandbox from the terminal or through commands sent by the CLI, SDK, or MCP server.

### Can I open a terminal in a Celesto sandbox?

Yes. Click Terminal on a running sandbox in the Celesto console, or run celesto computer ssh NAME --cloud from your own terminal.

### Is celesto computer ssh real SSH?

For cloud sandboxes it opens an interactive shell over a secure WebSocket, so you need no SSH keys and no open port 22. Use it the way you would use an SSH session.

### Can I see the sandbox's screen?

Yes, on the browser templates. Console → Display shows the live desktop, read-only or with mouse and keyboard control. From code, computer.display() in Python or createDisplayConnection() in TypeScript returns a connection URL.

### Can my agent drive a web browser?

Yes. Create a sandbox from the browser-agent template and call computer.browser() in Python or createBrowserConnection() in TypeScript. Connect Playwright or Puppeteer to the returned CDP URL.

### Can I expose a web server from a sandbox?

Yes. Publish any port from 1024 to 65535 and get a public HTTPS URL. Each sandbox can publish up to 4 ports, from the console, CLI, SDK, or MCP.

### Do files survive when a sandbox stops?

Yes. The disk, installed packages, and the CelestoFS workspace survive stop and start, and a stopped disk is kept for 30 days. Running processes end when the sandbox stops.

### Can I turn off internet access?

Yes. Create the sandbox with networkPolicy: { mode: "off" } in the TypeScript SDK to block outbound connections for untrusted code.

### How do Claude Code and other agents use Celesto?

Connect them to the hosted MCP server at https://mcp.celesto.ai/mcp. Its tools create, start, stop, and delete sandboxes, run commands, and publish ports. In Claude Code, run claude mcp add --transport http celesto https://mcp.celesto.ai/mcp.

### Is Celesto open source?

Yes. Celesto sandboxes run on celesto, our Apache-2.0 microVM package at github.com/CelestoAI/celesto. The same Python package runs a sandbox on your machine with Computer() or in Celesto Cloud with Computer(provider="cloud").

### How is each sandbox isolated?

Every sandbox is its own KVM virtual machine with its own kernel, so code in one sandbox cannot see another. It is not a container on a shared kernel.

### What does a sandbox cost?

Sandboxes are billed only while running, from $0.015 per hour for Micro (1 vCPU, 2 GB). New accounts get a one-time $5 trial credit with no card required.