STEP 01

Install the core.

The engines (reconciler, context) are stdlib-only: zero runtime dependencies, Python 3.11 or newer. The themed terminal deck is a separate, optional extra so the core install never has to pull in a TUI framework it doesn't need.

core

$ pip install orrery

optional: the deck

$ pip install 'orrery[tui]'  # themed terminal deck (textual)

Installing from a clone instead of a package does the same thing: pip install . from the repository root (pip install '.[tui]' for the deck extra).

STEP 02

Let it check its own install.

Almost nothing in this category can prove it is still correctly installed a month later. doctor is that proof, run on demand: it confirms the right Python is present, the package imports, every reconciler check is registered, and every subcommand is reachable. It never asks you to trust a note that says the install is fine.

verify

$ orrery doctor

Real output, captured from a fresh install (your Python and package versions will differ):

  [ok ] python>=3.11: 3.12
  [ok ] stdlib tomllib: present
  [ok ] import orrery: 0.1.0
  [ok ] reconciler checks: all present
  [ok ] import context engine: ok
  [ok ] cli entry point: orrery.cli:main
  [ok ] tui extra (optional): installed

healthy

Add --json for a machine-readable result a CI job can check.

STEP 03

Declare the shape of a box.

A profile is a TOML file that declares what a box should be: which paths must exist, which edges it should be able to reach, which secrets are wired to which consumers, which counts must never quietly shrink. It is per-installation data, not part of the core, and it never leaves your box: write it locally, keep it out of git if it names real hosts or paths. The engine and its checks do not change between installs, only the profile does.

illustrative profile.toml

schema = 1
box = "runtime-01"

[[checks]]
id = "declared-presence"
required = [
  "/etc/myapp/config.toml",
]

[[checks]]
id = "floors"

  [[checks.floors]]
  name = "backup archive floor"
  path = "/var/backups/myapp"
  kind = "file_count"
  min = 7

The full syntax for all six checks ships in the repo at profiles/example.toml, commented field by field. Copy it, point it at real paths, delete what you don't need.

The six checks a profile can declare
Check id	What it proves
org-map	One source-of-truth table agrees with every consumer that re-encodes it.
fleet-reach	Actual ssh reach matches the declared matrix; a reopened denied edge is drift.
declared-presence	Required members exist; planned-absent paths stay absent.
secret-edges	The secret-to-consumer graph holds. Value-blind: it never reads a secret value.
floors	Counts stay within declared floors and ceilings; a floor far below reality is flagged stale.
managed-settings	The enforcement layer stays root-owned and unwritable by anyone else.

STEP 04

Run the reconciler.

A fact here is not "declared", it is declared and its probe passes, continuously. Reconcile is report-only: it measures and prints findings, it never changes a box. Try it immediately against the example profile that ships in the repo, unedited: every path in it is a placeholder, so every check reports drift or failure. That is the honest, correct behavior, not a bug.

the shipped example, unedited

$ orrery reconcile --profile profiles/example.toml

Real output, unedited, run against the example profile as shipped:

reconciler: example

[declared-presence]
  FAIL  /path/that/must/exist: required member is missing  (expected 'present', observed 'absent')
  info  /path/that/should/not/exist/yet: absent as planned

[fleet-reach]
  FAIL  some-box: declared-reachable link is DOWN  (expected 'reachable', observed 'unreachable')
  ok    a-deliberately-closed-box: correctly denied

[floors]
  DRIFT example content floor: floor path is missing  (expected 'present', observed 'absent')
  DRIFT example digest budget: floor path is missing  (expected 'present', observed 'absent')

[managed-settings]
  FAIL  /path/to/an/enforcement/file: required enforcement file is missing  (expected 'present', observed 'absent')
  info  /path/to/a/planned/managed-settings/file: not yet in place (planned)

[org-map]
  warn  org-map: source of truth unreadable: /path/to/orgs.tsv

[secret-edges]
  DRIFT some-store/tokens/example -> /path/to/a/consumer/that/references/it: declared consumer file is missing or unreadable  (expected 'references the secret', observed 'file absent')
  warn  some-store/tokens/example: discover_root does not exist: /path/to/scan/for/undeclared/references

summary: OK=1 INFO=2 WARN=2 DRIFT=3 FAIL=3  ->  DRIFT DETECTED (exit 1)

Once your own profile names real paths and real boxes, point at it the same way:

your profile

$ orrery reconcile --profile my-fleet.toml

Every finding above came from a live probe against the box, not from a note that once said something was true. Exit code is 0 when the worst finding is at or below info, 1 on drift or worse, 2 if the profile itself fails to load (a clean message, never a traceback). Add --json for scripting, --check ID to run one check, --ssh HOST to measure a remote box read-only.

Reference

Every command.

The whole surface is five subcommands. orrery with no arguments, or orrery --help, prints this same list.

orrery <command> [args]
Command	What it does
reconcile	Run a reconciler profile (drift report). `--profile PATH` required.
context	Resolve the context for a working directory. `--config PATH` required.
deck	Launch the themed terminal deck (needs the `tui` extra).
doctor	Verify this installation.
version	Print the version.

Free core

Unlimited boxes. One operator. Self-host.

The core is free to run, study, and modify at any scale of your own fleet, because software that reaches every one of your boxes should be auditable in full, not taken on trust.

The core

ESS Orrery

AGPL-3.0-or-later

Unlimited boxes, one operator, self-hosted. Zero runtime dependencies, read-only, identity-free.

The reconciler and its six checks
Per-directory context isolation
A self-verifying install (doctor) and the full CLI
The themed terminal deck (optional extra)

The commercial layer adds governed-autonomy for consequential work, a hosted control plane, and the graphical fleet view. See the full model →

If it doesn't check out

Common first-run snags.

orrery doctor reports anything other than "healthy": Check the failing line's Python version requirement (3.11 or newer) and reinstall with pip install --force-reinstall orrery. The tui line is the one exception: "not installed (optional)" is a pass, not a failure.
orrery deck exits with a tui extra error: Real message: "the deck needs the 'tui' extra (textual not installed). install with: pip install 'orrery[tui]'". Run that install line, then retry.
orrery reconcile exits with code 2: The profile itself failed to load, a TOML syntax error or a bad path. The tool prints profile error: ... to stderr, never a raw traceback. Fix the file named after --profile and rerun.

From a blank shellto a fleet held in true.