> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/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 using the install script, pip, or build from source — sets up the Firecracker or QEMU backend automatically based on 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 `smolvm-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 `~/.smolvm/bin`, so it needs no system folders. On macOS, setup installs QEMU via Homebrew.
</Note>

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 `~/.smolvm/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 `SMOLVM_FIRECRACKER_DIR` so later Celesto commands can find the binary:

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

Celesto looks for Firecracker in this order:

1. The `--firecracker-dir` flag, if passed.
2. The `SMOLVM_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, `~/.smolvm/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 (`smolvm-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).

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/CelestoAI/celesto.git
    cd celesto
    ```
  </Step>

  <Step title="Build and install">
    ```bash theme={null}
    uv sync --extra dev
    ```

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

    <Check>
      Confirm the local build loaded correctly:

      ```bash theme={null}
      uv run python -m smolvm_core
      ```

      It prints a report of the native helpers available on your machine.
    </Check>
  </Step>

  <Step title="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.
  </Step>
</Steps>

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 smolvm-core`, then rerun `uv run python -m smolvm_core` to confirm Python loads your new build.
</Tip>

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

## Requirements

<Tabs>
  <Tab title="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>

  <Tab title="macOS">
    * macOS on Apple Silicon or Intel
    * [Homebrew](https://brew.sh)
    * Python 3.10+
  </Tab>
</Tabs>

When `SMOLVM_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 SMOLVM_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.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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
    ```
  </Accordion>
</AccordionGroup>

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

## Uninstall

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

<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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/smolvm/quickstart">
    Run your first sandbox in minutes
  </Card>

  <Card title="Basic usage" icon="gear" href="/smolvm/guides/basic-usage">
    Learn about VM configuration options
  </Card>

  <Card title="Custom images" icon="box" href="/smolvm/guides/custom-images">
    Build your own VM images with custom tools
  </Card>

  <Card title="API reference" icon="book" href="/smolvm/api/smolvm">
    Explore the complete API
  </Card>
</CardGroup>


## Related topics

- [Disposable macOS environments](/smolvm/guides/macos-sandboxes.md)
- [Install SmolFS](/smolfs/installation.md)
- [Install Agentor and configure LLM providers](/agentor/installation.md)
- [Troubleshooting guide](/smolvm/advanced/troubleshooting.md)
- [Firecracker, QEMU, and libkrun backends](/smolvm/concepts/backends.md)