> ## 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.
# Introduction
> XORCISE evaluates cyber AI agents against realistic mission environments — locally, on your own machine.
XORCISE puts an AI agent inside a real cyber-security mission, records everything it does, and grades it. The mission, the recording, and the grading all run on your machine.
*New here? Read this page, then [Quickstart](/start/quickstart), then [Your first run](/start/first-run) — about ten minutes. To understand the whole product, keep going through Core concepts.*
XORCISE is local by default, with three exceptions. Pulling a mission from the XORCISE library contacts the hosted catalog. Grading sends the distilled run transcript to the model provider you configure, and terrain attribution calls that provider too. Everything else stays on the machine: there is no analytics and no phone-home. [Security and isolation](/operate/security) names each exception and what it carries.
## What a run looks like
```mermaid theme={"theme":"css-variables"}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'JetBrains Mono, ui-monospace, SFMono-Regular, Consolas, monospace','fontSize':'12px','primaryColor':'#232323','primaryTextColor':'#f2ead6','primaryBorderColor':'#3a3a3a','secondaryColor':'#1a1a1a','tertiaryColor':'#141414','background':'#1a1a1a','mainBkg':'#232323','nodeBorder':'#3a3a3a','lineColor':'#6e6144','textColor':'#c7bb9f','clusterBkg':'transparent','clusterBorder':'#2f2f2f','edgeLabelBackground':'#1a1a1a','actorBkg':'#232323','actorBorder':'#3a3a3a','actorTextColor':'#f2ead6','actorLineColor':'#6e6144','signalColor':'#6e6144','signalTextColor':'#c7bb9f','labelBoxBkgColor':'#232323','labelBoxBorderColor':'#3a3a3a','labelTextColor':'#f2ead6','noteBkgColor':'#141414','noteTextColor':'#c7bb9f','noteBorderColor':'#3a3a3a','sequenceNumberColor':'#0a0805'},'flowchart':{'padding':26,'nodeSpacing':40,'rankSpacing':46},'sequence':{'useMaxWidth':true}}}%%
flowchart TD
A[Register agent] --> B[Pick a mission]
B --> C[Create a run]
C --> D[Connect your agent]
D --> E[Watch live]
E --> F[Read results]
```
* An **agent** is the named record of the AI system you are evaluating — XORCISE does not launch it, you connect it to a run ([Agents](/concepts/agents)).
* A **mission** is a deliberately vulnerable environment plus the rules for grading work done inside it ([Missions](/concepts/missions)).
* A **run** pairs one agent with one mission, and is the unit XORCISE records, ends, and scores ([Runs](/concepts/runs)).
* A **trace** is the OpenTelemetry your agent emits as it works, which XORCISE replays as a timeline, a terrain map, and an event feed ([Traces and events](/concepts/traces)).
* A **score** is the number XORCISE puts on a finished run, built from two equal halves ([How grading works](/concepts/grading)).
## How a score is built
Every finished run is scored `overall = 0.5 × deterministic + 0.5 × judge`.
```mermaid theme={"theme":"css-variables"}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'JetBrains Mono, ui-monospace, SFMono-Regular, Consolas, monospace','fontSize':'12px','primaryColor':'#232323','primaryTextColor':'#f2ead6','primaryBorderColor':'#3a3a3a','secondaryColor':'#1a1a1a','tertiaryColor':'#141414','background':'#1a1a1a','mainBkg':'#232323','nodeBorder':'#3a3a3a','lineColor':'#6e6144','textColor':'#c7bb9f','clusterBkg':'transparent','clusterBorder':'#2f2f2f','edgeLabelBackground':'#1a1a1a','actorBkg':'#232323','actorBorder':'#3a3a3a','actorTextColor':'#f2ead6','actorLineColor':'#6e6144','signalColor':'#6e6144','signalTextColor':'#c7bb9f','labelBoxBkgColor':'#232323','labelBoxBorderColor':'#3a3a3a','labelTextColor':'#f2ead6','noteBkgColor':'#141414','noteTextColor':'#c7bb9f','noteBorderColor':'#3a3a3a','sequenceNumberColor':'#0a0805'},'flowchart':{'padding':26,'nodeSpacing':40,'rankSpacing':46},'sequence':{'useMaxWidth':true}}}%%
flowchart TD
O["Overall score"] --> D["Deterministic half — 50%
checks XORCISE runs itself"]
O --> J["Judge half — 50%
a model reads the mission rubric"]
```
The **deterministic** half is mechanical: XORCISE runs the mission's checks against the evidence the run produced — the flag, the artifacts your agent submitted, the telemetry it emitted — and sums the weights of the ones that pass. The **judge** half is a model reading the mission's rubric and scoring the work against it. XORCISE bundles no model and no key: you point it at an OpenAI-compatible model of your own.
Those two halves are fixed at 50/50 and cannot be reweighted. With no judge model configured the judge half scores 0, so **the highest achievable score is 50%** — the deterministic half is not rescaled to compensate. A run that comes back at 42.5% on a host with no judge has not failed; it has been graded on half the scale.
You can configure a judge afterwards and re-evaluate a finished run without running it again. [How grading works](/concepts/grading) shows the arithmetic end to end.
## What you need
XORCISE installs with `pip install xorcise`.
A running daemon, plus the Docker Compose v2 plugin. The legacy `docker-compose` v1 package does not satisfy it.
An OpenAI-compatible model and key for the judge half of the score. You can start without one.
Any AI agent you can hand a prompt to and that can reach a local REST endpoint.
XORCISE also needs `openssl`, which it uses to generate the local mission network's TLS certificate, and a writable `~/.xorcise`. `xorcise doctor` checks every prerequisite and prints the exact fix for anything missing. Linux is the primary platform, macOS is expected to work, and Windows is not addressed.
## Where missions come from
Missions come from the XORCISE library, a growing set of free missions that needs no account, key, or sign-in. Browse it with `xorcise mission list` and install a mission with `xorcise mission pull `, or do the same from the Missions page in the web UI. The mission then runs on your machine. [Missions](/concepts/missions) covers what a mission contains.
**Authoring your own mission is coming soon.** This release cannot install a mission from a local bundle: `xorcise mission ingest` reports that the feature is on its way, and the **Ingest a bundle** button on the Missions page opens a preview of the feature rather than installing anything. The mission manifest format is documented on [Missions](/concepts/missions) so you can prepare bundles in advance. Until authoring ships, pulling from the library is the supported way to get missions.
## Which path is yours
* **Use this path if you have an agent and want it graded.** [Quickstart](/start/quickstart), then [Your first run](/start/first-run).
* **Use this path if you want to see XORCISE work before wiring anything up.** [Quickstart](/start/quickstart) with `xorcise up --stub`, which needs no Docker.
* **Use this path if you want to prepare missions for other people's agents.** [Quickstart](/start/quickstart), then [Missions](/concepts/missions), which documents the manifest format ahead of the authoring release.
## Next steps
Install XORCISE and get the web UI open, in about five minutes.