When something is wrong

doctor is the first thing to run on any machine with a problem. It runs health checks and prints a verdict and a remedy for each one. It does not just report state, it says what to do.

evodira-local doctor

# For a monitoring check: stable schema, non-zero exit if any check failed
evodira-local doctor --json

These exist for one person: somebody on the far end of an SSH session to a machine they cannot see, holding a ticket. They answer, in order, what this thing is, what rules it is enforcing, how old those rules are, what it can run, and whether anything is broken. Every one is read-only and every one takes --json.

“This device is not enrolled”

The installer had no enrolment grant and none was staged. Re-run the install with EVODIRA_ENROLLMENT_TOKEN set, or enrol by hand. Note the default control-plane URL for a manual enrol is http://localhost:8000, so pass --control-plane-url or you will enrol against nothing.

evodira-local enroll \
  --control-plane-url https://app.evodira.com \
  --device-name 'Design MacBook' \
  --token-stdin

The enrolment link does not work

Open it in a browser first. The install page asks the control plane, read-only, what redeeming the grant would meet and names the reason: already used, revoked, expired, or not recognised. “Not recognised” is most often a link truncated when it was copied, or one belonging to a different control plane. Issue a fresh invite from Provisioning. Links are cheap and each machine gets its own.

“sudo: evodira: command not found”

There is no command named evodira. The console script is evodira-local and the packaged binary is evodira-local-agent.

The macOS install fails, or installs for nobody

You used sudo. The macOS installer refuses to run as root. It installs a LaunchAgent in your own login domain, and under sudo every path would resolve under /var/root and install a service for a user who never logs in. Run it without sudo. Equally, the Linux command on a Mac dies on the missing systemctl: the two scripts are not interchangeable.

Folders are approved but nothing is indexed

• macOS permission prompt unanswered. Documents, Desktop and Downloads are not readable until it is. Grant it in System Settings → Privacy & Security → Files and Folders, or deploy the PPPC profile by MDM for unattended installs.
• Autonomy ceiling is manual. Nothing runs until somebody starts it, with evodira-local run-once.
• The file types are not on the allow list. policy show names what may be opened. Anything not named is never opened.

An endpoint shows NOT REPORTING

• Run doctor on the machine.
• Check the service is up: launchctl print gui/$(id -u)/ai.evodira.local.agent on macOS, systemctl --user status ai.evodira.local.agent on Linux.
• Check policy show for a stale revision. A device that cannot reach the plane keeps its last-good policy rather than falling open, so an old revision is a connectivity symptom.
• Check the roster for WIPE UNANSWERED. A wiped device is not supposed to report.

An endpoint will not converge

Compare its POLICY REV against the profile’s current revision. If the device is reporting but not converging, its agent may be too old to receive operations at all. The fleet page states that explicitly above the table, and the fix is an agent upgrade via a rollout, not a policy change.

Ask returns nothing useful

Read the abstention reason before changing anything. “Limited by your permissions” is a role problem, not a knowledge problem; “insufficient evidence” usually means the relevant claims are still in the review queue. Chapter 9 has the four cases.

Ingestion dead-letter count is rising

Nothing retries a dead-lettered job, so this never clears itself. Open Ingestion and work the queue. A rising Failed count with a static dead-letter count is usually a transient upstream problem and needs no action.

A provenance certificate can be checked with no store, no network and no model. That is the point of having one.

evodira-local verify ./certificate.json \
  --public-key <base64-SubjectPublicKeyInfo>

Without --public-key a signature only proves internal consistency, not authorship, and the report says so rather than letting you read it as more than it is.

purge

Deletes local data and audit rows older than the policy retention windows. Run under the live tenant policy; the windows can be overridden for one run with --retention-days and --audit-retention-days.

wipe

Securely erases the local store, keys, credentials and config. Irreversible, and it does nothing at all without --yes. --keep-config leaves the runtime config and wipes only data, keys and credentials.

service uninstall

Removes the service. Config and state are left in place by design, so a reinstall does not lose the device identity.

• Bring the JSON. evodira-local doctor --json and evodira-local status --json answer most of the first round of questions before they are asked.
• Bring the event ID. Every row on Activity carries one, and it is the fastest way to point at a specific decision.
• Write to hello@evodira.com.