> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorcise.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install XORCISE, start it, and open the web UI on your own machine in about five minutes.

Install XORCISE and get it running. When you finish, the web UI is open and nothing is configured yet.

**Time:** about 5 minutes · **Interface:** command line

## Before you start

* **Python 3.12 or newer**, with `pip` or [uv](https://docs.astral.sh/uv/).
* **[Docker](https://docs.docker.com/get-started/get-docker/)**, with the daemon running and the Docker Compose v2 plugin installed. On Debian and Ubuntu that is `sudo apt install docker.io docker-compose-v2`.

<Tip>
  No Docker, or looking around first? Start with `xorcise up --stub` instead of `xorcise up`. Everything in this page still works, and the web UI opens as normal, but no mission actually runs.
</Tip>

## Install

<CodeGroup>
  ```bash pip theme={"theme":"css-variables"}
  pip install xorcise
  ```

  ```bash uv theme={"theme":"css-variables"}
  uv pip install xorcise
  ```
</CodeGroup>

That is the whole install. Confirm the command is on your `PATH`:

```bash theme={"theme":"css-variables"}
xorcise --version
```

## Start XORCISE

<Steps>
  <Step title="Check your host">
    `doctor` reports every prerequisite and prints the exact fix for anything that is missing or wrong.

    ```bash theme={"theme":"css-variables"}
    xorcise doctor
    ```

    ```text Output theme={"theme":"css-variables"}
    Environment
      ✓ python: Python 3.12.3
      ✓ Docker installed
      ✓ Docker daemon reachable
      ✓ Docker Compose v2 plugin present
      ✓ disk space: 256 GB free at /var/lib/docker
      ✓ openssl present
      ✓ /dev/net/tun: present
      ✗ data directory missing (~/.xorcise missing) — run 'xorcise up' to create it

    Services
      ○ XORCISE is not running — start it with: xorcise up

    Fix the ✗ items above, then re-run xorcise doctor.
    ```

    Before you have ever started XORCISE, the data-directory line is expected and `doctor` exits `1`. The next step creates the directory. Any other `✗` is real, and its remediation text tells you what to do.
  </Step>

  <Step title="Start it">
    ```bash theme={"theme":"css-variables"}
    xorcise up
    ```

    ```text Output theme={"theme":"css-variables"}
    prepared the database
    local Headscale ready at https://<host-ip>:443
    ⊕ X O R C I S E v<version> — Trust Evidence, not Claims.
    xorcise up — UI at http://127.0.0.1:3001/ui
    Next steps:
      1. Register an agent  xorcise agent register --name my-agent
      2. Add a judge model  xorcise config set-model --name <model> --key <key>
      3. Pick a mission     xorcise mission list
      4. Install it         xorcise mission pull <id>
      5. Create a run       xorcise run create --agent my-agent --mission <id>
      6. Launch your agent  xorcise run launch-cmd <run-id>
    ```

    The first start creates `~/.xorcise`, writes a starter config, and prepares the database, so it takes longer than later ones. Ports move up to the next free port when something else holds them, so use the URL `up` prints rather than assuming `3001`.

    Running `xorcise up` again while XORCISE is already running prints `already running — UI at <url>` and exits `0`. Re-running it is safe.
  </Step>

  <Step title="Open the web UI">
    Open the URL from the previous step in your browser. `xorcise ui` prints it again at any time.

    On a fresh install the home page is a **Get started** checklist. It becomes the **Dashboard** once you have your first run.
  </Step>

  <Step title="Confirm it is healthy">
    ```bash theme={"theme":"css-variables"}
    xorcise status
    ```

    ```text Output theme={"theme":"css-variables"}
    XORCISE status

     Service         State     Address
     ──────────────────────────────────────────────────
     Interface       Healthy   http://127.0.0.1:3001/ui
     REST API        Healthy   http://127.0.0.1:3001
     OTLP receiver   Healthy   http://127.0.0.1:4318
     Docker          Healthy   local daemon

    All services are healthy.
    ```

    `status` probes the REST API, the OTLP receiver, and the Docker daemon, and exits `1` if any of them is down.
  </Step>
</Steps>

<Frame caption="The Get started page once XORCISE is up. The readiness line is the fastest way to confirm the install is sound before you create a run.">
  <img src="https://mintcdn.com/xorciseai/73cVaorGzBMhO39b/images/setup.png?fit=max&auto=format&n=73cVaorGzBMhO39b&q=85&s=2ec03d6af019770f2dcaf9c93d95aa99" alt="The Get started page showing the four-step checklist complete and a readiness banner" width="2880" height="1800" data-path="images/setup.png" />
</Frame>

## Stop XORCISE

<CodeGroup>
  ```bash down theme={"theme":"css-variables"}
  xorcise down
  ```

  ```bash down --keep-data theme={"theme":"css-variables"}
  xorcise down --keep-data
  ```
</CodeGroup>

`down` stops XORCISE, removes leftover mission containers, and tears down the local mission network. It keeps your config, your API keys, your installed missions, and every run and result.

`xorcise down --keep-data` stops XORCISE and leaves everything else running, including the local mission network.

<Warning>
  `xorcise down --purge` deletes all of `~/.xorcise` — your config, your API keys, your installed missions, and every run and result. It asks for confirmation unless you add `--yes`, and in a non-interactive shell without `--yes` it refuses and exits `2`.
</Warning>

## Next steps

<Card title="Your first run" icon="play" href="/start/first-run">
  Register an agent, pick a mission, and end holding a real score.
</Card>