> ## 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: secure microVM sandboxes for AI agents

> Introduction to Celesto — an open-source microVM sandbox with sub-second boot, hardware isolation, and persistent state for running AI agents safely.

# Celesto

[Celesto](https://github.com/CelestoAI/celesto) gives AI agents their own disposable computer. Each microVM (A lightweight virtual machine that provides hardware-level isolation with near-instant startup, combining the speed of containers with the security of full VMs) boots in milliseconds, runs any code or software you throw at it, persists files and state across sessions, and disappears when you're done — built for scale in production.

> [card] Sub-second boot
>
> VMs ready in \~413 ms.

> [card] Hardware isolation
>
> Stronger security than containers.

> [card] Network controls
>
> Open, off, or destination-restricted outbound access.

> [card] Browser sandbox
>
> Full browser agents can see and control.

> [card] Host mounts
>
> Give sandboxes access to local directories.

> [card] Snapshots
>
> Save and restore VM state instantly.

> [!NOTE]
>
> **Building with agent sandboxes?** Get Celesto release notes, implementation patterns, and early-access updates.
>
> \[Join the Celesto interest list]\[celesto-interest-list]

## Quickstart

**1. Install Celesto**

```bash theme={null}
curl -sSL https://celesto.ai/install.sh | bash
```

This installs everything you need and configures your machine. See [Installation](https://celesto.ai/docs/celesto/installation.md) for manual install and requirements.

**2. Run your first sandbox**

> [tab] Python
>
> Create `quickstart.py`:
>
> ```python quickstart.py theme={null}
> from celesto import Celesto
>
> vm = Celesto()
> result = vm.run("echo 'Hello from the sandbox!'")
> print(result.stdout.strip())
> vm.stop()
> ```
>
> Run it:
>
> ```bash theme={null}
> python quickstart.py
> ```

> [tab] CLI
>
> ```bash theme={null}
> celesto sandbox create --name my-sandbox
> celesto sandbox ssh my-sandbox
> echo 'Hello from the sandbox!'
> exit
> celesto sandbox stop my-sandbox
> ```

You should see:

```text theme={null}
Hello from the sandbox!
```

### CLI usage

Create and manage sandboxes from the terminal:

```bash theme={null}
celesto sandbox create --name my-sandbox
celesto sandbox ssh my-sandbox
celesto sandbox list
celesto sandbox stop my-sandbox
```

Mount host directories for read-only access:

```bash theme={null}
celesto sandbox create --mount ~/Projects/my-app
celesto sandbox create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data
```

Save and restore VM state with snapshots:

```bash theme={null}
celesto sandbox snapshot create my-sandbox
celesto sandbox snapshot list
celesto sandbox snapshot restore snap_abc123 --resume
```

Start a visible browser sandbox:

```bash theme={null}
celesto browser start --live
celesto browser list
celesto browser stop sess_a1b2c3
```

See the [CLI reference](https://celesto.ai/docs/celesto/cli/overview.md) for the full command list.

### Python SDK

Create and manage sandboxes from Python:

```python theme={null}
from celesto import Celesto

with Celesto() as vm:
    result = vm.run("echo 'Hello from the sandbox!'")
    print(result.stdout.strip())
```

Customize memory and disk for heavier workloads:

```python theme={null}
vm = Celesto(memory=2048, disk_size=4096)
```

Mount host directories:

```python theme={null}
with Celesto(mounts=["~/Projects/my-app"]) as vm:
    result = vm.run("ls /workspace")
    print(result.stdout)
```

Expose a port from the sandbox to your host:

```python theme={null}
with Celesto() as vm:
    vm.run("python3 -m http.server 8000 &")
    host_port = vm.expose_local(guest_port=8000)
    print(f"http://127.0.0.1:{host_port}/")
```

See the [API reference](https://celesto.ai/docs/celesto/api/celesto.md) for the full SDK documentation.

> [!TIP]
>
> Evaluating secure code execution, browser agents, or long-running agent environments? \[Tell us what you're building]\[celesto-interest-list] and we'll send the useful Celesto updates — or follow up personally if you're evaluating now.

## Next steps

> [card] [AI agent integration](https://celesto.ai/docs/celesto/guides/ai-agent-integration.md)
>
> Plug Celesto into PydanticAI, OpenAI Agents, LangChain, and more

> [card] [Port forwarding](https://celesto.ai/docs/celesto/features/port-forwarding.md)
>
> Expose services running inside a sandbox to your host machine

> [card] [Custom images](https://celesto.ai/docs/celesto/guides/custom-images.md)
>
> Build specialized images with your own tools pre-installed

> [card] [API reference](https://celesto.ai/docs/celesto/api/celesto.md)
>
> Explore the complete Celesto API

[celesto-interest-list]: https://tally.so/r/yPGeJd?utm_source=docs&utm_medium=smolvm_intro&utm_campaign=email_capture


## Related topics

- [Celesto architecture overview](https://celesto.ai/docs/celesto/concepts/overview.md)
- [Windows sandboxes in Celesto](https://celesto.ai/docs/celesto/guides/windows-guests.md)
- [Snapshot and restore Celesto sandboxes](https://celesto.ai/docs/celesto/features/snapshots.md)
- [Sandbox an OpenAI agent with Celesto](https://celesto.ai/docs/cloud/openai-agents.md)
- [Security model](https://celesto.ai/docs/celesto/concepts/security.md)


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