Moorhold docs

The moorhold command runs on the server Moorhold is installed on. The installer puts it at /usr/local/bin/moorhold, and it runs the CLI of the release in /opt/moorhold/current. Run it with sudo: the release's files are readable by root only, and without root the command says Run it with sudo: sudo moorhold <command> and stops.

This page describes the latest release (2026.11.4). Run moorhold --help on your server for the list your release has.

  • --profile full|core picks the install profile. full runs every component the Stack declares. core leaves out Apache Superset and DataHub, for an 8 GB server. light is the profile of a local install, for the Moorhold app for Mac, and a server refuses it. Commands that read -f, and check, start and plan-style commands, default to full when you don't give --profile. On an installed server, apply and start-at-boot use the profile the server runs.
  • --home <dir> is where Moorhold is installed (default /opt/moorhold). --secrets-dir <dir> is where its secrets are kept (default /etc/moorhold/secrets). You only need them for a test install in another place.
  • --dry-run shows what a command would do and changes nothing. --yes answers its question for you, for scripts. A command that asks a question and has no terminal stops unless you give --yes.
  • moorhold refuses an access key, a bucket's credentials or a backup repository key on the command line, where other users and logs can read them, and exits with code 2. Put each in a file of mode 0600 and give the file, or leave it out to be asked in a terminal without echo.
Code Meaning
0 Done, or nothing to do.
1 The command failed, or a check found a problem. The message says which.
2 The command line was wrong, or it carried a secret. Nothing ran.
3 upgrade refused before changing anything.
64 upgrade failed after a change, and the earlier release runs again.
65 upgrade failed after a change, and putting the earlier release back didn't finish.
66 upgrade finished and the new release runs, but the restore drill after it failed.
67 upgrade finished and the new release runs, but moorhold.service couldn't be written or enabled. Run sudo moorhold start-at-boot.
68 Both 66 and 67.
Terminal window
sudo moorhold status

On an installed server: the release, the hostname, whether the access key is kept, the backups and the health of every service. It exits 1 when a service isn't healthy, or when moorhold.service is missing or not enabled, because then the stack won't start again after a reboot.

Terminal window
sudo moorhold start [--profile full|core]

Writes the stack's boot secrets to /run/moorhold again and starts the stack with Docker Compose. moorhold.service runs it at boot.

Terminal window
sudo moorhold stop

Stops the stack with docker compose stop, keeping its containers and data. moorhold.service runs it at shutdown. start, or the next boot, starts it again.

Terminal window
sudo moorhold start-at-boot [--profile full|core]

Writes and enables moorhold.service, which runs moorhold start at boot and moorhold stop at shutdown, for the profile given or the one the server runs. It starts the unit when it isn't active. The installer and every upgrade run it too. Needs root.

Terminal window
sudo moorhold check [--hostname <name>] [--profile full|core] [--public-address-url <https-url>]

The installer's checks on their own: the system, memory for the profile, disk space and unallocated LVM space, sleep on a desktop install, ports 80 and 443, and the network check (DNS, where the name points, NAT loopback and carrier-grade NAT). It changes nothing, and exits 1 when a finding would stop an install. On an installed server you can leave out --hostname. install.sh --check runs the same checks before anything is installed.

Terminal window
sudo moorhold apply [--profile full|core]

With no -f and no store named, on an installed server: applies an edited /opt/moorhold/stack/stack.yaml. It renders and starts the stack again, applies the Stack to the stack's own store as the installer does, and prints what changed. With no install on the machine it refuses. Needs root. apply -f is in Working with a store.

Terminal window
sudo moorhold upgrade <version> [--profile full|core] [--access-key-file <path>]

Upgrades the server to <version>. It first runs the checks of upgrade --check and stops if one fails. Then it unpacks the verified release beside the running one and hands over to that release's own CLI, which:

  1. shows what changes;
  2. asks for approval when a tool changes version: with one admin, you type the tool's name; with two or more, a second admin approves it in the portal;
  3. pulls the images with the kept access key;
  4. edits the Stack in place and starts the new release over the same data;
  5. points /opt/moorhold/current at the new release only once it's up.

If the new release doesn't come up, the previous one is started again. Only one update runs at a time: if another is running, upgrade exits 1. Needs root.

upgrade --check, upgrade --dry-run

Section titled "upgrade --check, upgrade --dry-run"
Terminal window
sudo moorhold upgrade <version> --check
sudo moorhold upgrade <version> --dry-run

Downloads the named release into a temporary directory, checks its signature against the key the server trusts (/etc/moorhold/release.pub) and its sha256s, and runs the pre-upgrade checks: the version path, the stack's health, the kept access key, disk space, and the approval and manual steps the update needs. --dry-run also shows what the upgrade would change and do. Nothing on the server changes. Exits 1 when a check fails. Needs root.

Terminal window
sudo moorhold rollback [--database <db>] [--dry-run] [--yes]

Goes back to the rollback point the last upgrade took. It shows a plan listing every database it replaces and asks. Then it stops the apps, puts back the Postgres roles, replaces each database with its copy from the rollback point (keeping the current one under a dated name), puts back the Stack from before the upgrade, starts the earlier release with its own code and points /opt/moorhold/current at it.

With --database, only that database and the roles go back. The release and the Stack stay as they are. Needs root.

The backup commands use the installed project in /opt/moorhold/project, unless -o <outdir> names another.

Terminal window
sudo moorhold backup [--list [--from-bucket]]

Backs up every database of the stack now, into its encrypted restic repository (the Stack's spec.backups). --list lists the snapshots instead. --from-bucket with --list lists snapshots that are already in the bucket the server used for backups, without making a new backup.

Terminal window
sudo moorhold backup --lake [--dry-run] [--yes]

Backs up SeaweedFS's data volume as well, when the stack has one. It shows a plan and asks, stops the apps and SeaweedFS (a volume that's being written to isn't a consistent copy), takes the snapshot and starts them again.

Terminal window
sudo moorhold backup status

Where the backups are, the last backup, the last failure, the next run, the last restore drill and the last rollback point.

Terminal window
sudo moorhold backup drill

The restore drill of every database: backs each one up, restores it into a scratch database and compares every table's row count.

Terminal window
sudo moorhold backup key

Prints the backup repository key, on a terminal only. Without this key no backup can be restored. Keep a copy off the server.

Terminal window
sudo moorhold backup target
sudo moorhold backup target s3 --endpoint <https://host> --region <region> --bucket <bucket> [--path <path>] [--access-key-id-file <file>] [--secret-access-key-file <file>] [--dry-run] [--yes]
sudo moorhold backup target volume [--dry-run] [--yes]

Where the server's backups go. With no target, it says where they go now. s3 sends them to a bucket of your own, off this server. volume keeps them on this server. Before it switches, it checks the bucket. Then it takes the first backup there and a restore drill, and puts everything back as it was if that backup fails. Backups taken before the switch stay where they are.

--path defaults to moorhold/<hostname>, so each server has its own place in a shared bucket. The credentials come from files of mode 0600, or you're asked for them without echo. Needs root.

Terminal window
sudo moorhold backup restore <snapshot> --database <db> [--from-bucket] [--dry-run] [--yes]
sudo moorhold backup restore <snapshot> --lake [--dry-run] [--yes]

Puts one database, or SeaweedFS's data, back from a snapshot. It shows a plan and asks, stops the apps and refuses unless they stopped, restores into a new place, swaps it in by renaming (the old copy is kept) and starts the apps again. --from-bucket restores a database snapshot that is already in the bucket the server used for backups; it doesn't send a new backup there.

Terminal window
sudo moorhold backup restore-server --endpoint <https://host> --region <region> --bucket <bucket> [--path <path>] [--access-key-id-file <file>] [--secret-access-key-file <file>] [--repository-key-file <file>] [--replace-own-data] [--server-id <id>] [--dry-run] [--yes]

On a new server, after losing the old one: brings back the old server's databases and secrets from its backups in your bucket. It needs the old server's repository key, from a file of mode 0600 or typed without echo. It restores beside this server's databases, swaps them in, starts the stack, then takes a backup and a restore drill.

It refuses a server that holds data of its own (an admin password set, or sources of its own) unless you give --replace-own-data. When the path holds more than one server's backups, --server-id picks the one to recover. Needs root.

Terminal window
sudo moorhold backup pre-upgrade <from-version> <to-version>

Takes the rollback point an upgrade uses: every database and the roles, tagged with the two releases, then restic check. It isn't a test restore. upgrade runs it for you.

Terminal window
sudo moorhold backup drop-kept [<name>...] [--dry-run] [--yes]

Lists the copies a rollback or a restore kept (<db>_old<time>, <db>_r<time>, and the lake's .moorhold-before-restore-<time> folders), asks, and drops them, or only the ones you name. It never drops a copy whose own database isn't beside it, or a lake folder from a restore that stopped halfway.

Terminal window
sudo moorhold restore <database> --into <new-database> [--snapshot <id>]
sudo moorhold restore <database> --drill

Restores a database into a new one, never over an existing one. With --drill, it backs the database up, restores it into a scratch database, compares every table's row count and drops the scratch database.

Terminal window
sudo moorhold access-key set [--access-key-file <path>] [--keep-access-key-file]

Replaces the access key the server keeps, from a file of mode 0600 or typed in a terminal without echo. The registry checks the new key first. If it refuses it, the kept key stays as it was. Needs root.

Terminal window
sudo moorhold access-key forget

Deletes the kept access key. On a server, the next upgrade or rerun of the installer asks for one. A local install needs none. Needs root.

Terminal window
sudo moorhold users list

The portal's users, whether each is enabled, and their groups. Needs root.

Terminal window
sudo moorhold users reset-password <username> [--password-file <path>] [--no-temporary] [--reset-sign-in]

Sets a user's portal password, typed twice in a terminal without echo or read from a file of mode 0600. They choose a new one at their next sign-in, unless --no-temporary keeps the one you gave them. --reset-sign-in also removes their authenticator app and recovery codes and ends their sessions: they set up a new authenticator app at their next sign-in, and their passkeys still work. Needs root.

Terminal window
sudo moorhold mail password

Sets the password of the server's own mail settings. It reads it from standard input when you pipe it in, or asks twice in a terminal without echo. The password is kept root-only, given to the reconciler and the portal as file:///run/secrets/smtp-password, and sent to Keycloak on the reconciler's next pass. Needs root.

Terminal window
sudo moorhold plan
sudo moorhold plan check

With no -f: the server's plan, what it allows, and when it was last checked. plan check asks account.moorhold.dev now, sending the kept access key and the server's version. Needs root, because only root can read the key. plan -f is the dry run in Working with a store.

sample-data add, sample-data remove

Section titled "sample-data add, sample-data remove"
Terminal window
sudo moorhold sample-data add
sudo moorhold sample-data remove

add loads Moorhold sample: AI Release Radar, a dated snapshot of public data (credited to Epoch AI, under CC BY 4.0), as a ready-made source with its checks and marts, and starts its first load. remove deletes the source, its tables and catalogue entries, its mock supplier and the files add wrote. It keeps the supplier's password file while another source still names it, and says so. They use the profile the server runs unless you give --profile.

Terminal window
sudo moorhold relay init --provider hetzner|ionos [--hostname <name>] [--port <udp-port>]

For a server whose network can't take its hostname (no NAT loopback, carrier-grade NAT, or ports blocked). It makes the server's WireGuard key (mode 0600, kept on this server), chooses the tunnel's addresses and writes the relay's cloud-init, which holds public keys only.

Terminal window
sudo moorhold relay connect --endpoint <address[:port]> --relay-key <relay-public-key> [--profile full|core]

Brings the tunnel up with wg-quick, declares the relay in the Stack (spec.public.relay), restarts the front so it accepts the relay's PROXY protocol header, then runs the network check.

Terminal window
sudo moorhold relay disconnect [--profile full|core]

Takes the relay out of the Stack and the tunnel down.

Terminal window
sudo moorhold relay check [--hostname <name>] [--public-address-url <https-url>]

The network check on its own. Exits 1 when something's wrong.

Terminal window
sudo moorhold power setup

For tools named in the Stack's spec.public.sleepWhenIdle: makes the directory moorhold-wake asks through and turns on moorhold-power.path. The next moorhold start mounts it. Needs root.

Terminal window
moorhold install --lock <file> --hostname <name> [--access-key-file <path>] [--profile full|core] [--acme production|staging] [--keep-access-key-file] [--sample-data | --no-sample-data] [--no-network-check] [--public-address-url <https-url>]

What install.sh runs once it has checked the release's signature. You don't run it yourself. It writes the Stack for the hostname, generates every secret (files of mode 0600, never printed), pulls each image by digest with the access key, starts and applies the stack, and shows the one-time setup code (on a terminal; otherwise where to read it) and the URL. It runs the network check before the stack asks for its certificate, unless --no-network-check. A fresh install loads the sample only with --sample-data. Installing again keeps what the server has. See the installer reference for the options install.sh takes.

Terminal window
moorhold install --local --lock <file> [--access-key-file <path>] [--no-sample-data]

For one person, in a virtual machine on their own computer, as the Moorhold app for Mac installs it. It takes no hostname, makes no certificate and runs no network check. It runs the light profile, with each tool on 127.0.0.1 and the portal at http://127.0.0.1:47300. It needs no access key: it pulls Moorhold's images without a login unless you give a key or the install kept one. install.sh refuses --local on a server.

These commands work on a store you name: --database-ref <secret-ref> (or the MOORHOLD_DATABASE_URL_REF environment variable) for Postgres, otherwise --state <file> (default .moorhold/state.json). They're for development and for running Moorhold outside an installed server. Every command that reads -f also takes --profile. Use the same profile for up, plan and apply.

Terminal window
moorhold validate -f <dir|file>

Parses and validates the resources and lists them.

Terminal window
moorhold plan -f <dir|file>

Shows what apply would change. Nothing is changed. Exits 1 if the plan has an error.

Terminal window
moorhold apply -f <dir|file> [--wait <seconds>]

Makes the store match the files, then reconciles proposals. The pass runs under the reconciler's lease. While a running reconciler holds it, apply stores the files and waits, up to --wait seconds (default 600), for that reconciler to reconcile them.

Terminal window
moorhold reconcile [--every <seconds>] [--wait <seconds>]

Reconciles what's stored, under the reconciler's lease as apply does. --every keeps running the reconciler's loop, leader-elected on Postgres, until you stop it.

Terminal window
moorhold delete <Kind/name> [--force] [--hard-catalog] [--wait <seconds>]

Tears one resource down and forgets it. --force removes it even while dashboards or other objects depend on it. --hard-catalog also removes its catalogued datasets and purges removed DAGs' run history from Airflow. Without it, the delete is soft and those stay.

Terminal window
moorhold status --database-ref <secret-ref>

The store's resources and their conditions: Ready, Drifted, Degraded and BlockedByDependents.

Terminal window
moorhold events [<Kind/name>]

The reconciler's event log.

Terminal window
moorhold export [--kind <Kind>] [--out <file>]

The desired state as YAML, so you can take your stack with you. It keeps labels and annotations, except the one-shot safety annotations (moorhold.adopt, moorhold.force-delete, moorhold.catalog-delete). It holds secret references only, never a value. --out writes a file of mode 0600.

Terminal window
moorhold proposals [list]
moorhold proposals show <name>
moorhold proposals approve|reject|withdraw <name> --as <user> --password-ref <secret-ref>

Lists and shows change proposals. A decision needs a person's portal sign-in (--as and a secret reference to their password), and the same rules apply as in the portal. The next reconcile pass acts on it.

Terminal window
moorhold audit [--user <name>] [--since <time>]

The audit log, from a Postgres store only. Component reads show the agent whose delegated token made them.

Terminal window
moorhold manifest check [-f <dir|file>] [--manifest <file>]

Validates the supported-versions manifest, runs the licence gate and, with -f, compares the stack's components with it. Exits 1 when a check fails.

Terminal window
moorhold db migrate --database-ref <secret-ref>

Creates or upgrades the Postgres schema.

admin bootstrap, admin password, admin disable

Section titled "admin bootstrap, admin password, admin disable"
Terminal window
moorhold admin bootstrap [--password-ref <secret-ref>]
moorhold admin password [--password-ref <secret-ref>]
moorhold admin disable

The portal's hidden break-glass local admin, on a Postgres store. bootstrap creates it once. password rotates its password and prints it once. disable turns local-admin sign-in off and ends its sessions.

Terminal window
moorhold render -f <dir|file> -o <outdir> [--manifest <file>] [--no-portal] [--profile full|core]

Renders the stack as a Docker Compose project. It holds no secret values: boot-secrets.json lists the references to write at start-up.

Terminal window
moorhold up -f <dir|file> [-o <outdir>] [--manifest <file>] [--runtime-dir <dir>] [--allow-disk] [--no-portal] [--profile full|core]

Renders the stack, writes its boot secrets to <runtime-dir>/secrets (a tmpfs, default /run/moorhold) and starts it with Docker Compose. --allow-disk is for development machines without a tmpfs. --no-portal leaves out Moorhold's own containers (the reconciler, collector, portal MCP server and portal), for example to run them on the host.

Terminal window
moorhold down [-o <outdir>] [--volumes]

Stops the stack and removes its boot secrets. --volumes also deletes its data.

Moorhold's systemd units, and the reconciler's container, run these. You don't need to run them, and their output is meant for the command that calls them.

Command Run by
upgrade --approved moorhold-requests.service, as the last step of requests run-due, when an admin approves an update in the portal. You can also run it by hand, as root. It checks each approved request again (the admins, the release it was asked from, its expiry), runs the pre-upgrade checks, then upgrades. The Updates page shows the outcome.
upgrade --staged <release-directory> install.sh and upgrade, to hand over to the new release's CLI.
requests run-due [--if-due] moorhold-requests.service, when an admin approves a request or an update in the portal, and moorhold-requests.timer with --if-due. It checks each approved request that's due again and does it, such as more memory for one app, then installs approved updates.
memory sample moorhold-memory.timer. Samples the memory of the apps Moorhold sizes, for the portal's warning near the limit.
power run moorhold-power.service. Starts or stops the sleeping tools moorhold-wake asked for.
updates approved, updates record The update run (upgrade --approved, which moorhold-requests.service makes), inside the reconciler's container.
requests approved, requests record, requests stored requests run-due, inside the reconciler's container.
upgrade approvals, upgrade offer, upgrade record, upgrade record-grant upgrade, inside the reconciler's container.
users record-reset, mail record-password users reset-password and mail password, inside the reconciler's container.
backup own-data backup restore-server, inside the reconciler's container.