Quickstart

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

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.

Install

pip install xorcise

uv pip install xorcise

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

xorcise --version

Start XORCISE

Check your host

doctor reports every prerequisite and prints the exact fix for anything that is missing or wrong.

xorcise doctor

Output

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.

Start it

xorcise up

Output

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.

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.

Confirm it is healthy

xorcise status

Output

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.

The Get started page showing the four-step checklist complete and a readiness banner — 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.

Stop XORCISE

xorcise down

xorcise down --keep-data

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.

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.

Start here

Core concepts

Guides

Operate

Experimental

Resources

Before you start

Install

Start XORCISE

Stop XORCISE

Next steps

Your first run

​Before you start

​Install

​Start XORCISE

​Stop XORCISE

​Next steps

Your first run

Before you start

Install

Start XORCISE

Stop XORCISE

Next steps