Self-hosting
Upgrading
Move a node to a new release, what happens on its first start, and how to upgrade runners.
Versions and image tags#
Releases are numbered by date: YYYY.M.N, the year, the month and a counter that starts at 1 each month. 2026.11.5 is the fifth release in November 2026. The number says nothing about compatibility; each release’s notes list what an upgrade changes.
The node image has three kinds of tag:
ghcr.io/webstonehq/moru-node:latest: the newest release.ghcr.io/webstonehq/moru-node:2026.11.5: one release, as it was published.ghcr.io/webstonehq/moru-node:2026.11.5-r20261116: a weekly rebuild of that release with fresh Debian packages.latestmoves to each rebuild too.
latest is the easy choice. Pin a version (or a digest) if you want to upgrade only when you decide to, and read the changelog first.
moru-node --version prints the version a node runs.
Before you upgrade#
- Read the changelog for every release between yours and the new one. Each release’s “Upgrading” part lists breaking changes and anything you need to do.
- Take a backup. See Backups. It’s also your way back.
- Let running jobs finish. If the new release changes the index, the node rebuilds it on start, and jobs that were queued or running are lost (see below).
Upgrade the node#
With Docker Compose and latest:
docker compose pull && docker compose up -d With a pinned version, change MORU_IMAGE in .env, then run the same command.
On other setups:
- Fly.io:
fly deploy(after changing the tag infly.toml, if you pinned one). See Fly.io. - Kubernetes: change the image tag in the StatefulSet and apply it, or with
latest,kubectl rollout restart statefulset moru. - Railway, Render: redeploy the service.
- Without a container: stop the node, replace the binary, start it.
None of these pull new images by themselves, including the weekly rebuilds with security fixes. Upgrade on a schedule.
If you run the node from your own registry, copy the new version there first.
On a host with many nodes, upgrade the control node first, then the repo nodes, and keep every node within one protocol level of the control node. See Upgrading in Running many nodes.
What happens on the first start#
The node stops cleanly on SIGTERM, then starts on the new version with the same data directory. Watch its log on the first start:
- An index rebuild. If the release changes the index’s format, the node recreates the index from the repos before it serves. A node with many repos takes a little longer to start once. The rebuild loses operational state that isn’t kept in git: jobs that were queued or running, their logs, and webhook deliveries waiting to be sent. Start those jobs again afterwards.
- Migrations. Some releases change files in the data directory once, on the first start, and log what they did.
Going back#
A release can change what’s stored in the repos, so an older node may not read data a newer one wrote. To go back, restore the backup you took before upgrading into an empty data directory and run the older image on it. See Restore.
Upgrade runners#
Runners and the node don’t have to be upgraded together, but keep runners current. A node from a release image serves the runner of its own version, so after upgrading the node, run its install script again on each runner machine:
curl -fsSL https://moru.example.com/install-runner.sh | sh
It replaces moru-runner in ~/.local/bin (or MORU_RUNNER_BIN_DIR). Then restart the runner:
- Stop
moru-runner runwith Ctrl-C or SIGTERM. It stops taking jobs and finishes the ones it’s running. A second signal cancels them and cleans up; a third exits at once. - Start it again with the same command. The runner keeps its key and token in its cache directory, so it doesn’t need to register again.
The pinned Claude Code version isn’t tied to a release. You change it separately with moru-node pin-harness. See Agent profiles.