Skip to main content
Most of XORCISE configures itself. The first xorcise up creates everything it needs and never overwrites what you have edited, which leaves a short list of things you actually set: a judge model, optionally a terrain model, the mission library switch, and ports if the defaults collide.

​
What the first start creates

xorcise up checks its prerequisites before it writes anything, then bootstraps in order: it creates ~/.xorcise, scaffolds config.toml and a .env file at mode 0600, brings a fresh database to the current schema, provisions a local Headscale control plane with a self-signed TLS certificate, and starts the brain. Re-running up repeats the same path harmlessly — a scaffold is never overwritten, and provisioning is idempotent, so up also repairs a control plane whose containers disappeared after a reboot. Everything lands under ~/.xorcise, or under XORCISE_HOME if you set it before starting: One file in there is load-bearing and unmarked: headscale/.owned. It is the only thing that tells xorcise down that the running Headscale container and its volume belong to XORCISE. Delete it by hand and those resources are orphaned permanently — nothing will ever clean them up.
The Settings page showing the Evaluation, Mission Library and Runtime, and Diagnostics groups

The Settings page. Everything editable here is written to ~/.xorcise/.env, never to config.toml.

​
Where configuration lives

Four sources feed one settings object. Highest wins:
Two consequences are worth holding on to. A key set in both files is read from .env, not config.toml. And a XORCISE_* variable exported in your shell beats anything either file says, including for a CLI that is only talking to an already-running brain. The Settings page never writes config.toml. Every value it can change is written to ~/.xorcise/.env as a XORCISE_MODEL_*, XORCISE_JUDGE_*, XORCISE_TERRAIN_*, or XORCISE_CATALOG_ENABLED variable, and the file is re-chmoded to 0600 on every write. config.toml is world-readable and holds only non-secret shape, which is why the two are kept apart. The page groups its cards under three headings: Evaluation for how runs are graded, Mission Library & Runtime for the catalog and your environment, and Diagnostics for system health and connection. Every field name below matches a card in one of those groups. For the exhaustive list of keys, types, defaults, and their environment-variable names, see Configuration keys.

​
Configure the judge model

The judge produces half of every score, and XORCISE ships no model. Bring your own OpenAI-compatible endpoint and key. Grading sends the distilled transcript of a run to whatever provider you point it at, so this is the setting that decides where your run content goes.
Only the fields you pass change, and --key '' clears the key. Passing no options at all is a usage error rather than a silent no-op.
Either way the change applies to the next grade with no restart. Prove the key works rather than assuming it: xorcise config test calls the model and exits non-zero when it cannot, so it can gate a script, and the Test button on the card does the same thing. Test uses the saved key, not unsaved edits, so save first.
The key is write-only. Reading configuration back — over the API, in the UI, or with xorcise config show — returns only a four-character hint, never the key itself.

​
Bound the judge prompt

A long lab run can produce a judge prompt larger than the model’s context window, at which point the judge half is unreachable and the score degrades to deterministic-only. Two caps exist for exactly that failure, and they are the controls to reach for before you change models. The per-span cap defaults to 2000 tokens. It trims each span’s body to a head-and-tail window with a marker in between, so every action survives while a few enormous tool outputs stop dominating the transcript. Setting it to 0 disables trimming. The pre-flight transcript cap is off by default. Turned on, it rejects a run before the judge is called if the estimated prompt exceeds the ceiling. It is off deliberately: the local count is an estimate, so XORCISE prefers to let the call go through and surface the provider’s real error than to reject a prompt that would have fit.
Pass --transcript-max-tokens 0 to turn the pre-flight cap back off.
Changing a cap affects the next grade. A run whose judge already failed does not need re-running — re-evaluate it and the sealed evidence is graded again under the new settings.

​
Configure the terrain model

Terrain attribution maps each host and action on the terrain map back to the agent step that caused it, and it does that with a model call. By default it reuses your judge model and needs no configuration of its own. Override it only when you want attribution on a different model — each field you leave unset keeps falling back to the judge’s.
Pass an empty string to clear a field and fall back to the judge model, and use xorcise config test-terrain to call whichever model is currently effective.
Both routes report the effective model afterwards. Attribution also has a per-call transcript limit, defaulting to 256,000 tokens; an oversized batch is shrunk to fit rather than failed, so lower it only for a small-context attribution model.

​
Connect the mission library

The hosted XORCISE library is free and needs no API key, account, or sign-in of any kind — the client sends no credential. A catalog_key setting exists and is read by nothing. Connecting it makes library missions appear in the catalog and pullable on demand, including automatically at run start; pulling one contacts the hosted catalog and a container registry, and sends nothing about your runs.
Use xorcise catalog disconnect to turn it off and xorcise catalog status to check it.
Both write the same variable and take effect immediately. Read the result carefully: xorcise catalog status reports the saved setting and a live probe as two separate lines, and a saved preference is never reported as a verified connection. Disconnected means an empty remote library, not a stubbed one — your own ingested missions are unaffected.

​
Change ports

XORCISE binds two planes: the REST API and web UI on 3001, and the OpenTelemetry receiver on 4318. There is no third plane. If a port is busy, up scans up to 50 ports above it, moves, and prints a notice per move — so read the address up prints rather than assuming the default. To pin different ports, set them before starting — as a flag on up, or as keys in ~/.xorcise/config.toml, which is a flat file whose keys are the setting names:
Sibling commands discover a relocated brain on their own, so xorcise status and xorcise ui keep working without being told. There is no web UI equivalent.

​
Check your install

Three questions have three different answers: are the prerequisites on this host satisfied, are the ports answering, and what does the running instance believe about itself.
doctor checks prerequisites and prints an exact fix per failure. xorcise status probes the REST plane, the OTLP plane, and the Docker daemon. xorcise system asks the running instance what it sees, including its role, topology, and database schema.
The Modules card lists four modules: REST API under control, Docker under runner, Headscale under headscale, and OTLP receiver under collector. Each reads Healthy, Down with the probe’s own detail, or Not on this host — which is a statement about your role, not a failure. Access mode has one live option, Single operator · local trust; the multi-user option is listed as coming soon and is not shipped. The Environment card alongside them is read-only: your home path, the role and topology this process is running, and the database schema. When the schema reads behind — migration needed, the next section is what you want.

​
Upgrade XORCISE

up brings a schema-less database to the current version, but it will not migrate a database that already has data. That refusal is deliberate: migrating populated data stays an explicit decision, so up stops with database is behind the schema instead of touching your runs.
Nothing under ~/.xorcise is destroyed by any of that — the package upgrade touches only site-packages, and up re-renders the Headscale config and re-provisions its container idempotently. Run xorcise db upgrade only when up tells you the database is behind; there is no downgrade path, so back up xorcise.db before rolling a version back. If the migration fails with migration history mismatch, the database was stamped by a different build of XORCISE. Back up xorcise.db, then either run the build that created it or re-initialise from scratch.

​
Uninstall XORCISE

Order matters here, and getting it wrong leaves Docker resources behind with nothing left on the machine that knows how to find them.
The purge is what tears down the Headscale container, its network, and its named volume, reaps any leftover run containers, and removes ~/.xorcise. Doing it after pip uninstall is not possible. XORCISE never removes Docker images, so reclaim those yourself with docker system prune -a when you are ready.
xorcise down --purge deletes all of ~/.xorcise, including your .env — which is the only copy of your model API keys — your database, and every run, result, and trace. It asks for confirmation unless you pass --yes.

Configuration keys

Every setting, its type, default, and environment variable.

Troubleshooting

Symptom-first fixes for start, run, and grading failures.