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

# Install Celesto on Linux or macOS

> Install Celesto on Linux or macOS with the install script, pip, or from source. Celesto sets up the Firecracker or QEMU backend for your platform.

Celesto runs your code inside a fast, secure virtual machine. Under the hood it uses Firecracker on Linux and QEMU on macOS — both are tools for running isolated virtual machines. You don't need to pick one; Celesto detects your platform automatically.

## Quick install

Install Celesto with a single command:

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

This installs everything you need (including Python), configures your machine, and verifies the setup.

## Manual install

If you prefer to install step by step:

```bash theme={null}
pip install celesto
celesto setup
celesto doctor
```

On supported Linux and macOS systems, `pip install celesto` pulls in the matching `celesto-core` wheel automatically — most users do not need Rust installed.

> [!NOTE]
>
> Linux may prompt for `sudo` during `celesto setup` to install host packages (`nftables`, `iproute2`) and configure runtime permissions. Firecracker itself installs into your home directory at `~/.celesto/bin`, so it needs no system folders. On macOS, setup installs QEMU via Homebrew.

After setup on Linux, activate your new KVM group membership with `newgrp kvm`, or log out and back in.

### Choose where Firecracker is installed

On Linux, `celesto setup` installs Firecracker into `~/.celesto/bin` for the user who runs the command. The install is atomic: Celesto stages the binary in a temporary file and moves it into place, so a partially downloaded binary never replaces a working one. If a `firecracker` binary is already on your `PATH`, Celesto keeps using it and does not install a duplicate.

To install into a different folder for one setup run, pass `--firecracker-dir`:

```bash theme={null}
celesto setup --firecracker-dir "$HOME/.local/bin"
```

If that folder is not on your `PATH`, set `CELESTO_FIRECRACKER_DIR` so later Celesto commands can find the binary:

```bash theme={null}
export CELESTO_FIRECRACKER_DIR="$HOME/.local/bin"
celesto setup
```

Celesto looks for Firecracker in this order:

1. The `--firecracker-dir` flag, if passed.
2. The `CELESTO_FIRECRACKER_DIR` environment variable. When either of these is set, Celesto only looks in that folder.
3. Any `firecracker` binary on `PATH`.
4. The per-user default, `~/.celesto/bin/firecracker`.

This setting changes only where Firecracker lives. Images and sandbox state stay in their usual locations.

### Fedora Atomic desktops

Silverblue, Bluefin, and other Fedora Atomic systems work with the normal `celesto setup` command when the required host tools are already installed. Celesto never modifies the rpm-ostree deployment itself. If a required tool is missing, setup prints the exact `sudo rpm-ostree install` command to run, and asks you to reboot before retrying.

## Install from source

Build Celesto from source when you want the latest unreleased changes, or when you plan to modify Celesto itself. This compiles the Rust helper package (`celesto-core`) locally instead of downloading a prebuilt wheel.

You need [Git](https://git-scm.com), [uv](https://docs.astral.sh/uv/) (the Python package manager Celesto uses), and the [Rust toolchain](https://rustup.rs).

**1. Clone the repository**

```bash theme={null}
git clone https://github.com/CelestoAI/celesto.git
cd celesto
```

**2. Build and install**

```bash theme={null}
uv sync --extra dev
```

This creates a virtual environment, installs Celesto's dependencies, and compiles `celesto-core` from the Rust sources in the checkout.

> [!TIP]
>
> Confirm the local build loaded correctly:
>
> ```bash theme={null}
> uv run python -m celesto_core
> ```
>
> It prints a report of the native helpers available on your machine.

**3. Set up the host and verify**

```bash theme={null}
uv run celesto setup
uv run celesto doctor
```

`celesto setup` installs host dependencies — Firecracker on Linux, QEMU on macOS — and configures permissions. `celesto doctor` confirms your machine is ready to run sandboxes.

Run source-built commands with `uv run celesto ...` from the repository directory, so they use the build in your checkout. To use a plain `celesto` command instead, activate the environment with `source .venv/bin/activate`.

> [!TIP]
>
> Rebuild after changing Rust code with `uv sync --reinstall-package celesto-core`, then rerun `uv run python -m celesto_core` to confirm Python loads your new build.

For contribution guidelines, tests, and code style checks, see [CONTRIBUTING.md](https://github.com/CelestoAI/celesto/blob/main/CONTRIBUTING.md).

## Requirements

> [tab] Linux
>
> * Ubuntu, Debian, or Fedora. `celesto setup` installs missing host packages with `apt` or `dnf`. On rpm-ostree systems such as Fedora Atomic, it prints the `rpm-ostree` command to run instead. Other distributions work but you may need to install host dependencies yourself
> * KVM support — the kernel feature that lets Celesto run virtual machines. Check with `ls /dev/kvm`
> * x86\_64 architecture
> * Python 3.10+

> [tab] macOS
>
> * macOS on Apple Silicon or Intel
> * [Homebrew](https://brew.sh)
> * Python 3.10+

When `CELESTO_BACKEND` is unset or `auto`, Celesto picks the best backend that is actually installed on your machine. It prefers Firecracker on Linux and QEMU on macOS, and falls back through Firecracker → QEMU → libkrun so it never resolves to a hypervisor your host cannot run.

If nothing suitable is installed, `celesto sandbox create` fails immediately with a plain-English message telling you what to install — before downloading the base image, so a missing hypervisor no longer costs you a multi-hundred-MB download.

To force a specific backend:

```bash theme={null}
export CELESTO_BACKEND=firecracker   # or qemu, libkrun, or auto (the default)
```

## Optional extras

Install extras for agent framework examples or the web dashboard:

```bash theme={null}
pip install celesto pydantic-ai openai-agents langchain playwright   # agent framework examples
pip install "celesto[dashboard]"  # fastapi, uvicorn, websockets
pip install "celesto[all]"        # all Celesto extras
```

> [!TIP]
>
> If you only need Celesto as a sandbox, the base `pip install celesto` is all you need.

## Troubleshooting

> [accordion] Linux: KVM not available
>
> If `/dev/kvm` doesn't exist, enable virtualization:
>
> ```bash theme={null}
> sudo modprobe kvm_intel   # Intel CPUs
> sudo modprobe kvm_amd     # AMD CPUs
> ls -l /dev/kvm
> ```
>
> For cloud VMs, enable nested virtualization in your hypervisor settings.

> [accordion] Linux: Permission denied on /dev/kvm
>
> Add your user to the `kvm` group and activate it:
>
> ```bash theme={null}
> sudo usermod -aG kvm $USER
> newgrp kvm
> ```

> [accordion] macOS: qemu-system not found
>
> Ensure Homebrew's bin directory is in your `PATH`:
>
> ```bash theme={null}
> export PATH="/opt/homebrew/bin:$PATH"   # Apple Silicon
> export PATH="/usr/local/bin:$PATH"      # Intel
> ```

For golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see the [upstream installation guide](https://github.com/CelestoAI/celesto/blob/main/docs/installation.md).

## Upgrade from SmolVM

SmolVM is now Celesto. New installations store configuration and state under `~/.celesto` and read `CELESTO_*` environment variables.

If you used SmolVM before, Celesto reads your existing `~/.smolvm` images, runtime, and state while no Celesto directory exists. Upgrade before you delete the old directory.

`SMOLVM_*` environment variables still work for now, and Celesto prints a deprecation warning for each one. Replace each with its `CELESTO_*` equivalent, for example `SMOLVM_BACKEND` with `CELESTO_BACKEND`, before the next major release.

The `smolvm` command and the `smolvm` Python import were removed. Use the `celesto` command and `from celesto import ...` instead. Published images from before the rename use the old guest protocol, so rebuild custom images with the renamed guest agent.

## Uninstall

```bash theme={null}
pip uninstall celesto
rm -rf ~/.local/state/celesto ~/.celesto
```

> [!WARNING]
>
> The `rm -rf` command deletes all sandbox state and cached images. Skip it if you might reinstall Celesto later and want to keep your cached base images.

## Next steps

> [card] [Quickstart](https://celesto.ai/docs/celesto/quickstart)
>
> Run your first sandbox in minutes

> [card] [Basic usage](https://celesto.ai/docs/celesto/guides/basic-usage.md)
>
> Learn about VM configuration options

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

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


## Related topics

- [Disposable macOS environments](https://celesto.ai/docs/celesto/guides/macos-sandboxes.md)
- [Troubleshooting guide](https://celesto.ai/docs/celesto/advanced/troubleshooting.md)
- [celesto windows](https://celesto.ai/docs/celesto/cli/windows.md)
- [Windows sandboxes in Celesto](https://celesto.ai/docs/celesto/guides/windows-guests.md)
- [celesto doctor](https://celesto.ai/docs/celesto/cli/doctor.md)


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