Docs
Docs menu

The data directory

What a node keeps in its data directory, which parts are secret, and which the node can rebuild.

A node keeps everything in one directory: /data in the container image, ./data by default otherwise (--data or MORU_DATA). Code and collaboration data (changes, requests, comments, reviews, Bake-offs) live in the git repos. The other files are keys, accounts and node configuration, plus an index built from the repos.

moru-node backup covers everything that can’t be rebuilt. See Backups.

Layout#

data/
├── repos/<owner>/<name>.git     canonical repos: code and all collaboration data
├── keys/                        signing keys (secret)
│   ├── node.key                 the node's key
│   ├── users/<handle>.key       keys of password accounts
│   ├── agents/                  agents' keys, and ~ci.key for CI jobs
│   ├── orgs/                    organizations' keys
│   ├── host/                    a did:plc host's rotation and signing keys
│   └── oauth-client.key         AT Protocol sign-in client key
├── host.json                    which host identity this directory has
├── secrets/                     accounts and credentials (secret)
│   ├── users/<handle>.json      accounts: role, password hash, token IDs
│   ├── atproto/bindings/        AT Protocol people's binding proofs
│   ├── github/                  GitHub tokens and GitHub App keys
│   ├── nodes.json               node codes and enrollment tokens (control node)
│   └── setup.json               the pending setup link (until there's an admin)
├── orgs/<name>.json             organizations: members, roles, settings
├── access/<owner>/<name>.json   each repo's visibility, collaborators, branch rules
├── signup/                      who may join with AT Protocol, and requests to join
├── runners.json                 registered runners and their token IDs
├── profiles.json                agent profiles
├── repo-policies.json           merge rules set with repo-policy
├── trusted-attesters.json       other hosts whose attestations this node trusts
├── checkpoints/                 what this node's key signed, for revoking it later
│   └── nodes/<did>/             checkpoints the host's other nodes reported (control node)
├── host/
│   ├── revocations.json         the node keys this host revoked, and from when
│   └── checkpoints/             the checkpoint each of those revocations vouches from
├── hosts/<did>.json             what the node learned about each host from its repos and the PLC directory
├── nodes.json                   the host's nodes (control node)
├── placement/.pending/          repos being created on a node (control node)
├── admin/                       drains, moves, revocations and restores the node carries out
│   └── done/                    the finished ones, kept 30 days
├── moving/<owner>/<name>.json   repos paused while they move to another node
├── moving-in/                   copies of repos on their way to this node
├── moved/                       repos that left this node, kept 14 days
├── nodes-cache.json             a joined node's copy of the host's nodes (repo node)
├── control-cache.json           a joined node's copy of the host-wide state (repo node)
├── control-contact.json         when it last heard from the control node (repo node)
├── key-binds.json               what it may sign for people and agents (repo node)
├── restored.json                a restored repo node's backup, until it joins
├── github/apps/                 registered GitHub Apps
├── links/<owner>/<name>.json    repos linked to GitHub
├── webhooks/<owner>/<name>.json each repo's webhooks, with their secrets
├── prefs/                       people's preferences and notification read state
├── trash/                       deleted repos, kept 7 days
├── scratch/                     agents' scratch repos
├── ci/artifacts/<run-id>/       CI runs' artifacts, kept 30 days
├── tmp/                         working space for merges
└── index.sqlite                 the index (plus -wal and -shm files)

Files and directories appear when they’re first needed: a new node has only some of them. The files marked “control node” and “repo node” exist only on a host with many nodes. Lock files (access.lock, runners.json.lock, nodes.json.lock, secrets/nodes.json.lock, host/revocations.json.lock, hosts/.lock) and dot-files are the node’s own and not worth backing up.

What each part is#

PathWhatRebuildableSecret
repos/Every canonical repo, with Moru’s data under refs/moru/.noholds your code
keys/The node’s key, the host’s keys, and the keys the node keeps for password accounts, agents and organizations.noyes
host.jsonThe host identity: key or plc, and for plc the directory and cached DID log.no
secrets/Accounts (password hashes, token IDs, pending invites), AT Protocol binding proofs, GitHub tokens, GitHub App private keys and client secrets.noyes
orgs/, access/Organizations, and each repo’s visibility, collaborators and protected branches. The node enforces access from these files. orgs/.pending/ holds organizations whose did:plc isn’t registered yet.no
signup/mode.json (Open, Ask to join or Closed) and one file per request to join in requests/.no
runners.jsonRegistered runners: names, DIDs, owners, labels and token IDs.no
profiles.jsonAgent profiles: which agents and models are offered, and pinned Claude Code versions.no
repo-policies.jsonMerge rules: require_pinned, required_ci and require_locked_actions; schedule_as, who scheduled CI runs act for.no
trusted-attesters.jsonA JSON list of host DIDs (or node did:keys) whose attestations count. This node’s own host is always trusted.no
checkpoints/Which collaboration objects this node’s key signed in each repo, and their tips: the newest 144 distinct snapshots, taken every 10 minutes. revoke-node needs one from before a key leaked. On a control node, checkpoints/nodes/<did>/ keeps those the other nodes reported, each named by when the control node received it: at most one per node every 5 minutes, for 30 days (the newest is always kept).no
host/revocations.jsonThe node keys this host revoked with revoke-node or retire-node (on a control node, also every node it revoked), each with the time it’s revoked from. The node refuses those keys from then on in every repository, even a copy that lacks the revocation, and writes the revocation into such a copy before serving it. See How trust works.no
host/checkpoints/The checkpoint each of those revocations vouches from, one file per key and time, never pruned.no
hosts/One file per host: the DID documents and revocations the node found in its repositories, and the host’s log from the PLC directory with when it was fetched.yes
nodes.jsonOn a control node: every node of the host, with its key ID, role, internal URL, certificate and state.no
secrets/nodes.jsonOn a control node: node codes and enrollment tokens, and who joined with each. Only hashes of the codes and tokens, but treat it as secret like the rest of secrets/.noyes
placement/.pending/On a control node: reservations of repo names while another node creates or imports them. Each lapses on its own.not needed
nodes-cache.jsonOn a repo node: its copy of the host’s nodes, kept current by the control node.yes
control-cache.jsonOn a repo node: its copy of the host-wide state (accounts without secrets, organizations, runners, where each repo lives), so it can route and show names after a restart before the control node answers.yes
control-contact.jsonOn a repo node: when it last heard from the control node, so a restart while the control node is down keeps only what’s left of --control-grace.not needed
key-binds.jsonOn a repo node: the control node’s signed authorizations for this node to sign for people and agents, kept so they can write while the control node is down. Tied to this node’s key.yes
admin/Drains, moves, revocations and restores, one file each, which the running node carries out step by step; the CLI and Settings → Network hand them over here. A restore’s uploaded or copied backup waits here as <id>.tgz until it’s done. A finished one moves to admin/done/, where it’s kept 30 days.noa backup holds secrets
moving/On a repo’s node during a move: the repos paused for it, with their target. The pause survives a restart.not needed
moving-in/On a move’s target: the copy being received, until the switch puts it in repos/. Also where a restore unpacks a backup’s repos before they’re placed.not neededholds code and secrets
moved/Repos that moved to another node, and copies a restored node set aside because the host has them elsewhere: kept 14 days as a fallback, never served.not neededholds code and secrets
restored.jsonWritten by restore of a repo node’s backup: the old node and its repos. The node joins in its place, then deletes it.no
github/, links/Registered GitHub Apps and repos linked to GitHub.no
webhooks/Each repo’s webhooks, including the secrets they sign with.noyes
prefs/People’s preferences, such as the diff layout, and which notifications they’ve read.no
trash/Deleted repos, each with its access entry, webhooks and GitHub link, until they’re purged after 7 days.noholds code and secrets
ci/artifacts/The artifacts CI jobs upload, one folder per run, kept 30 days (less if a workflow asks). Deleted with the repository when it leaves the trash. Not in backups, and they stay here when a repository moves to another node.
scratch/Agents’ scratch repos. Each lives at most a day (MORU_SCRATCH_TTL).not needed
tmp/Short-lived working copies for merges and GitHub delivery.not needed
index.sqliteThe index: a fast view of the repos for the UI and API, plus jobs, CI runs, events and webhook deliveries.yes

keys/host/rotation.key deserves the most care on a did:plc host: whoever holds it controls the host’s DID.

What can be rebuilt#

  • index.sqlite: the node rebuilds it when it’s missing or when an upgrade changes its format. moru-node rebuild-index rebuilds it by hand, with the node stopped. What it loses is operational: jobs that were queued or running and their logs, CI runs and their logs, CI failure notifications, the event history, and webhook deliveries waiting to be sent. The results of CI jobs for changes’ revisions are attestations in the repos, so they survive. The index also lists the CI artifacts in ci/artifacts/: after a rebuild nothing lists them, so their files are deleted after 24 hours. CI run numbers (github.run_number) are counted in the index too, so they start again at 1 after a rebuild, as they do on the new node after a repository moves; the first run numbered after the upgrade that added them is 1.
  • scratch/ and tmp/: nothing depends on them once the jobs or merges using them are over.
  • nodes-cache.json, control-cache.json and key-binds.json on a repo node: it gets them again from the control node.
  • hosts/: the node reads every repository’s host objects again when it starts, and fetches the PLC directory’s logs again. What it learned from repositories deleted since is gone.
  • placement/.pending/: each reservation lapses 10 minutes after its operation’s longest allowed run.
  • The index on a control node, which holds where each repo lives, the job map and the change feed: the repo nodes’ reports fill it again within seconds.

Everything else is either in git (repos/) or node configuration that exists only here, and a backup includes both. Backups leave out the index, hosts/, ci/artifacts/, scratch/, trash/, tmp/, lock files and dot-named files and directories (placement/.pending/ among them, but not orgs/.pending/), and on a host with many nodes moving/, moving-in/, moved/, the backups waiting in admin/, nodes-cache.json, control-cache.json, control-contact.json and key-binds.json. A repo node’s backup also leaves out keys/node.key, host.json and admin/, so it restores as a new node. They include checkpoints/ (with the reports kept under checkpoints/nodes/), host/ on every kind of node, nodes.json, secrets/nodes.json and a control node’s admin/ requests.

On a runner#

A runner keeps its state in its own cache directory, not in the node’s data directory: its key, its token, a copy of each repo, and the working copies of running jobs. A runner that runs CI jobs may also have .runner/ci.toml, the secrets it gives CI jobs. The node never holds CI secrets: it knows their names and scopes, not their values. See The cache directory.

Command menu
Search for a page, repository, change or request, or run a command