Self-hosting
Configuration
Every moru-node serve flag and the environment variable that sets it, with defaults and what each one changes.
The node is configured with flags on moru-node serve, and every flag has an environment variable. In the container image and the Compose bundle you’ll use the variables: put them in .env (Compose) or in your platform’s settings. A flag on the command line wins over its variable.
moru-node serve --help prints the same list for the version you run.
The ones you’ll set#
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_PUBLIC_URL | --public-url | http:// + the listen address | The URL people use to reach the node. It goes into clone URLs, runner leases, invite and sign-in links. Set it in every real deployment. A node listening on all addresses without it (as in the image) warns at start, since its links would say http://0.0.0.0:7070. |
MORU_TRUSTED_PROXIES | --trusted-proxy | none | Reverse proxies whose X-Forwarded-For header the node believes. An address, a CIDR range, or private for loopback and the private ranges. Comma-separated in the variable; repeat the flag. Without it, every request seems to come from the proxy, so the sign-in rate limits count all clients together. |
MORU_LANDING | --landing | off | Signed-out visitors to / get a page introducing Moru, and the node serves the comparison pages under /compare, robots.txt, sitemap.xml, llms.txt and llms-full.txt. For a node that offers Moru to the public; leave it off for a team’s own node. Set the variable to true. |
MORU_EVENTS_RETENTION | --events-retention | keep everything | Delete events older than this, for example 30d. At least 1h. A client that resumes its event stream from a deleted point is told to reload. |
private means 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1/128 and fc00::/7. The Compose bundle sets it, since Caddy reaches the node over a Docker network.
Where the node listens and keeps its data#
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_DATA | --data | ./data | The data directory. The image sets it to /data. See the data directory. |
MORU_LISTEN | --listen | 127.0.0.1:7070 | The address and port the node listens on. The image sets it to 0.0.0.0:7070. |
MORU_RUNNER_DOWNLOADS | --runner-downloads | none | A directory of runner archives (moru-runner-<target>.tar.gz) to serve at /download/runner/, with /install-runner.sh to install from them. The image sets it, so a node installs runners of its own version. |
--data is a global option: every moru-node command takes it, not only serve. The node checks at start that it can write the data directory, and says which user it runs as if it can’t.
Host identity#
These are global options too. They decide what the node signs as. Read host identity before you change them: the choice is permanent for a data directory.
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_IDENTITY | --identity | the one the data directory has, or key for a new one | key: an offline did:key (the node’s own key). plc: a did:plc registered with the PLC directory on the first serve. plc needs MORU_PUBLIC_URL. A value that differs from the data directory’s refuses to start. |
MORU_PLC_URL | --plc-url | the one the host registered at, or https://plc.directory | The PLC directory, where a did:plc host is registered and other did:plc hosts’ logs are fetched from (a did:key host uses it for those too). People’s AT Protocol identities resolve here too. Only serve (and host --refresh) contacts it: for the host’s own log and, about every 12 hours, for the logs of the other did:plc hosts the node trusts as attesters or imported repos named. See How trust works. |
MORU_NO_PLC_REFRESH | --no-plc-refresh | off | Don’t fetch other did:plc hosts’ logs from the PLC directory (about every 12 hours for trusted attesters and hosts imported repos named), for a node that can’t reach it. Trust then rests on the DID documents the repos carry. See How trust works. |
Agents, jobs and scratch repos#
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_JOB_QUEUE_TTL | --job-queue-ttl | 12h | How long a job waits for a runner before it times out. A developer’s laptop may be asleep, or a usage limit may need hours to reset. Cut to the scratch TTL minus 6 hours, the longest run. |
MORU_SCRATCH_TTL | --scratch-ttl | 24h | How long an agent’s scratch repo lives. |
MORU_PRUNE_EXPIRE_DAYS | --prune-expire-days | 14 | Days before git may prune unreachable objects in canonical repos. Must be longer than the scratch TTL, because scratch repos borrow the canonical repo’s objects. |
MORU_SCRATCH_QUOTA_MIB | --scratch-quota-mib | 50 | The largest push an agent may make to its scratch repo, in MiB. |
MORU_PUSH_QUOTA_MIB | --push-quota-mib | 2048 | The largest push to a repository, in MiB. 0 removes the limit. Imports aren’t pushes and aren’t limited. |
MORU_AGENT_TOKEN_TTL | --agent-token-ttl | 4h | How long an agent’s task token lasts. |
MORU_SCRIPTED_PROFILES | --scripted-profiles | off | Adds scripted agents (fake-tidy, fake-reviewer and others) to the profiles, for development and demos. They need a runner offering the fake harness. |
GitHub#
You only need these if the node’s address as GitHub sees it differs from MORU_PUBLIC_URL, or you use GitHub Enterprise. See GitHub for connecting it.
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_GITHUB_PUBLIC_URL | --github-public-url | the public URL | The URL GitHub links back to: a GitHub App’s homepage and redirects. GitHub refuses localhost, so it must be a public HTTPS address. |
MORU_UI_ORIGIN | --ui-origin | none | Other origins the web UI is served from, besides the public URL’s. GitHub’s redirects carry codes, so the node only sends them on to the public URL’s origin and these. AT Protocol sign-ins started from one of them also come back to it. Most nodes leave it unset. Comma-separated in the variable; repeat the flag. |
MORU_GITHUB_URL | --github-url | https://github.com | GitHub’s web host, for registering GitHub Apps and cloning. |
MORU_GITHUB_API_URL | --github-api-url | https://api.github.com | GitHub’s REST API. |
A node reached through a proxy at another host name must set MORU_PUBLIC_URL to that address, or list it in MORU_UI_ORIGIN. Otherwise connecting GitHub and registering GitHub Apps are refused.
Webhooks#
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_WEBHOOKS_ALLOW_PRIVATE | --webhooks-allow-private | off | Lets webhooks call internal addresses: loopback, private networks, link-local. Turn it on for a node whose integrations run inside its own network. Set the variable to true. |
See Webhooks.
A host with many nodes#
Leave these unset for a node that runs on its own. Running many nodes explains them.
| Variable | Flag | Default | What it does |
|---|---|---|---|
MORU_ROLE | --role | all | all (repositories and the host-wide state), control (only the host-wide state) or repo (only repositories). control and repo need an internal listener. |
MORU_INTERNAL_LISTEN | --internal-listen | none | The listener for the host’s other nodes, on a private network. Setting it makes a node with role all the host’s control node. Can’t share the public port. |
MORU_INTERNAL_URL | --internal-url | none | The URL the other nodes reach this node’s internal listener at. Required with MORU_INTERNAL_LISTEN. |
MORU_CONTROL_GRACE | --control-grace | 5m | How long a repo node keeps accepting tokens after it lost contact with the control node. |
MORU_REPLAY | --replay | none | fly: hand small requests for another node back to Fly.io’s proxy with fly-replay. Needs FLY_APP_NAME and FLY_MACHINE_ID. |
MORU_CONTROL_URL | --control | none | A repo node’s first start: the control node’s internal URL, to join with MORU_JOIN_TOKEN. Ignored by other roles. |
MORU_JOIN_TOKEN | --join-token-file | none | The enrollment token for that join (the flag takes a file holding it). Ignored by other roles. |
MORU_MAX_RESTORE_UPLOAD | --max-restore-upload | 20G | The largest backup a site admin may upload from the web app to restore a revoked or retired node’s repositories on this node. Bytes, or with K, M, G or T (powers of 1024). A reverse proxy in front needs to allow bodies as large. |
Durations#
Durations are a number and a unit: 90s, 15m, 4h, 7d. A number on its own is seconds.
Values the node refuses#
The node refuses to start when:
- the scratch TTL isn’t shorter than the prune expiry (
MORU_PRUNE_EXPIRE_DAYS), - the agent token TTL is zero,
- the events retention is shorter than an hour,
- a
MORU_UI_ORIGINentry isn’t anhttporhttpsorigin, MORU_IDENTITYorMORU_PLC_URLdiffers from what the data directory’s host has,- the role is
controlorrepowithout an internal listener,MORU_INTERNAL_LISTENandMORU_INTERNAL_URLaren’t set together, or the internal listener uses the public port, MORU_REPLAY=flyis set without an internal listener or without Fly’s variables,- the data directory joined a host and the role isn’t
repo, or the role isrepoand it hasn’t joined one (and has noMORU_CONTROL_URLand token to join with).
Other variables#
A few commands read secrets from the environment, so they stay out of your shell history:
MORU_IMPORT_TOKEN: the token for the source node, formoru-node import-repo.MORU_GITHUB_TOKEN: a GitHub token, formoru-node link-githubwithout--token-file.
Runners have their own settings. See moru-runner commands.