Documentation

READ IT WHERE IT SHIPS.

Elixir’s documentation ships inside the artifact, so it can never disagree with the version you installed. This page is the map: each card names the file and what it answers, and you read it from your own install rather than from a browser.

Getting started

Quickstart

What the tool does once installed, end to end. Every command in it was run against a fresh package install.

docs/using-it.md

Day one

What to expect from a fresh install, and why "it doesn’t do anything" is the correct first observation.

docs/bootstrap.md

Installation →

Requirements, source install, VM walkthrough, executors, MCP and a synthetic first incident.

Architecture

How the pieces fit: the boundary, the queue, the executor and the verification path.

docs/architecture.md

Agent identity

Why identity is issued rather than derived, and what an Agent ID survives.

docs/agent-identity.md

Executor contract

What an adapter must implement, what it is never given, and why a model runtime may not hold a shell.

docs/executor-contract.md

Runtime adapters

How Elixir observes a fleet, and the honest verification status of each adapter.

gateway/runtime/adapters/README.md

Interfaces

Public API

Reporting an incident, reading the incident, the result and the evidence.

docs/public-api.md

MCP

The six tools, the client configuration, and why the approving tools do not exist.

docs/mcp.md

Providers

Every executor, its capability matrix and its real certification status.

docs/providers.md

Governance

Authority

What a grant must carry, and why self-expansion is the case with no one else watching.

policies/authority.md

Approvals

Who may approve, what an approval satisfies, and what it never clears.

policies/approvals.md

Evidence

The evidence contract: provenance, reproduction and redaction.

contracts/evidence.schema.json

Billing

What Elixir charges for, and what a lapsed subscription does not do.

docs/billing.md

Quick reference

THE COMMANDS YOU WILL ACTUALLY USE

Set up and checkbash

npm ci                       # exactly the certified lockfile
npm run bootstrap            # what this install still needs
npm run doctor               # can it run a session, serve an API, serve MCP
npm test                     # the suite ships with the tool

Operatebash

npm run api                  # the public incident API
npm run mcp                  # the MCP server
npm run executor -- --list   # what is queued and eligible
npm run liveness             # is anything working the queue
npm run escalations          # what needs a person

Identity and accessbash

npm run agents:migrate -- --new-organization --name "Acme" --apply
npm run agents:migrate -- --new-agent --organization org_… --apply
npm run api:key -- --issue --name "support fleet" --scopes incidents:create,incidents:read
npm run api:key -- --list
npm run api:key -- --revoke <id>

MCP tools

elixir_list_agentsList the protected agents this key can see.
elixir_get_agentRead one agent by its durable Elixir Agent ID.
elixir_report_incidentReport an incident. Reporting is not approving.
elixir_get_incidentRead an incident and its current status.
elixir_get_resultRead the canonical recovery result, once one exists.
elixir_get_evidenceRead the evidence the result was judged against.

Troubleshooting

THE FIRST THINGS TO CHECK

Common symptoms and where to look
Symptom	Where to look
The doctor says INERT	Usually nothing is wrong. INERT means working as designed and waiting on a decision only a person may make — most often that no production authority has been granted, which is correct for a new install.
Incidents are accepted and never complete	Nothing is working the queue. Elixir ships no supervisor unit, so the executor runs when a person or a timer runs it. Check npm run liveness and npm run executor -- --list.
liveness always says idle	It may be reading a different data directory from the one the gateway writes. Set WFA_GATEWAY_DATA explicitly — cron and plain shells inherit neither that nor GATEWAY_DATA_DIR.
Queue liveness says UNKNOWN on a fresh install	Start npm run api once. The API creates the request store, then reports that an empty registry will refuse incidents. Stop it with Ctrl+C, finish enrollment, and run the doctor again. If the API has already run, verify WFA_GATEWAY_DATA.
The executor refuses to start a session	The configured provider is unavailable or unauthenticated. Elixir does not fall back to another one. npm run doctor names which.
MCP connects and every tool fails	It should not — the server refuses to start without ELIXIR_API_KEY. If tools fail, check ELIXIR_API_URL points at a running API.
A result was refused for unverified tests	A result claiming passing tests that nothing observed running is rejected by design. Run npm run attest -- <result.json> before submitting one by hand.

Still stuck? Elixir is in private alpha — get in touch through the alpha, and include the output of npm run doctor with any keys redacted.