Docs
Docs menu

moru-runner commands

Every moru-runner command with its flags and environment variables, plus the install script's settings.

moru-runner runs agent and CI jobs for a node, directly on its machine as its own user, with no sandbox (see Where to run a runner). It connects out to the node and never listens for connections. It runs on Linux (x86_64, arm64) and macOS, and needs git on its PATH. For setting one up step by step, see Add a runner.

moru-runner <COMMAND>

moru-runner --help and moru-runner <command> --help print the same for the version you run. moru-runner --version prints the version.

Install#

A node installs runners of its own version:

curl -fsSL https://moru.example.com/install-runner.sh | sh

On its own, the script only downloads and unpacks the binary; moru-runner register does the rest. Given a one-time code, it registers and starts the runner too, which is the command Runners → Add a runner shows:

curl -fsSL https://moru.example.com/install-runner.sh | sh -s -- --code mrr_… --name laptop --run

--code and --name register with them, --node names the node (default: the one that served the script), and --run starts the runner in the current directory. It reads two environment variables:

VariableDefault
MORU_RUNNER_BIN_DIR~/.local/binWhere to put moru-runner.
MORU_RUNNER_RELEASESthe node’s /download/runnerWhere to download the archives from.

register#

Registers this runner with a one-time code from the node’s UI (Runners → Add a runner). Before it spends the code, it checks for git. It saves the runner’s token in <cache-dir>/.runner/token.json, where run finds it.

moru-runner register [OPTIONS] --node <NODE> --code <CODE> --name <NAME>
FlagVariableDefault
--node <NODE>MORU_NODERequired. The node’s URL.
--code <CODE>Required. The code the UI showed (mrr_…). Single use, valid for 15 minutes.
--name <NAME>Required. A name for this machine. The node puts your handle in front: jon-laptop. Not linux, macos, x64 or arm64.
--cache-dir <CACHE_DIR>./runner-cacheWhere the runner keeps its key, token and object cache. Pass the same one to run.
--key-file <KEY_FILE><cache-dir>/.runner/runner.keyThe runner’s signing key.
--replaceRegister even though the cache directory already holds a runner’s token. That runner can’t start from this directory afterwards: one directory, one runner.
moru-runner register --node https://moru.example.com --code mrr_… --name laptop

A runner registered this way gets a 30-day token and renews it itself.

run#

Leases jobs from the node and runs them until it’s stopped, or, with --once, runs at most one.

moru-runner run [OPTIONS]
FlagVariableDefault
--node <NODE>MORU_NODEthe one register savedThe node’s URL.
--token <TOKEN>MORU_RUNNER_TOKENthe one register savedA runner token from moru-node create-runner-token. Pass it in the variable, not the flag: agents can read other processes’ command lines.
--cache-dir <CACHE_DIR>./runner-cacheWhere the per-repo object cache, key and token live.
--max-jobs <MAX_JOBS>1Jobs to run at once.
--harness <HARNESSES>every agent it hasAgents to offer (repeatable): claude, codex, gemini, fake or one from agents.toml. See Agents.
--agents <AGENTS>MORU_AGENTS<cache-dir>/.runner/agents.tomlThe file that defines your own agents. Named here, it must exist.
--kind <KINDS>all threeJob kinds to take: implement, review or ci (repeatable). --kind ci makes a CI-only runner.
--only-namedTake only CI jobs that name this runner, and only from pushes and manual starts. Implies --kind ci. See Only named jobs.
--schedulesWith --only-named, take scheduled runs too.
--ci-config <CI_CONFIG>MORU_CI_CONFIG<cache-dir>/.runner/ci.tomlThe secrets this runner gives CI jobs, and its cache size. Named here, it must exist. See CI secrets.
--actions-url <URL>MORU_ACTIONS_URLhttps://github.comWhere CI jobs’ actions are fetched from, as <url>/<owner>/<repo>: a mirror, or a directory of <owner>/<repo>.git repositories.
--container-cli <CLI>MORU_CONTAINER_CLIdocker, then podman, on PATHThe container engine for CI jobs: docker, podman, a path, or none to turn containers off. See Containers.
--work-dir <WORK_DIR>MORU_WORK_DIR<cache-dir>/.runner/workWhere CI jobs check out: <work-dir>/<owner>/<name>, one folder per repository. See The work directory.
--onceTake at most one job, run it, and exit. See One job and exit.
--key-file <KEY_FILE><cache-dir>/.runner/runner.keyThe runner’s signing key.
--claude-version <CLAUDE_VERSION>MORU_CLAUDE_VERSIONthe latestClaude Code version for profiles that don’t pin one.
--claude-releases-url <CLAUDE_RELEASES_URL>MORU_CLAUDE_RELEASES_URLhttps://downloads.claude.ai/claude-code-releasesWhere Claude Code releases come from.

Each job gets a working copy and runs in a process group of its own. The runner kills whatever the job left running and removes the working copy when the job ends. An agent job’s working copy is in the cache directory; a CI job’s is in the work directory.

The work directory#

A CI job checks out its commit in <work-dir>/<owner>/<name>, the same folder for every CI job of that repository, as GitHub gives every job of a repository the same workspace path. A build that one job makes and another runs, such as a test archive whose binaries hold absolute paths into the checkout, then finds the paths it expects. The job’s other files (its temporary folder, command files and outputs) stay in its own folder in the cache directory.

  • The folder is emptied before the checkout and removed when the job ends. Nothing carries over from one job to the next; use caches for that.
  • A runner runs one CI job of a repository at a time, since they share the folder. Other repositories’ CI jobs and agent jobs still use its other slots. To run one repository’s jobs side by side, start more runners, each with its own work directory.
  • For a build that crosses machines, give their runners the same --work-dir.
  • The runner takes the directory for itself when it starts (two runners can’t share one), makes it private to its user, and removes what an earlier run left there. It refuses a directory that already holds files and isn’t a runner’s, so a mistyped path doesn’t get emptied.
  • A runner that doesn’t take CI jobs doesn’t use it.
moru-runner run --kind ci --work-dir /opt/moru/work

Model credentials#

Agents run as the runner’s user, with the runner’s environment and home directory. Each uses that user’s login if there is one, or its own variables if set:

  • Claude Code: CLAUDE_CODE_OAUTH_TOKEN (a Claude subscription token from claude setup-token) or ANTHROPIC_API_KEY.
  • Codex: CODEX_API_KEY.
  • Gemini CLI: GEMINI_API_KEY, or GOOGLE_API_KEY with Vertex AI.

The runner redacts these, and OPENAI_API_KEY and GOOGLE_CLOUD_ACCESS_TOKEN, from the log lines it sends to the node. Agents can read them.

moru-runner run
ANTHROPIC_API_KEY=… moru-runner run --cache-dir /var/lib/moru-runner --max-jobs 4

One job and exit#

With --once, the runner renews its saved token if that’s due, asks the node for a job once, waiting up to 20 seconds, and if one comes, runs it to the end and reports it. Then it exits. It’s for autoscalers, Kubernetes Jobs and spot machines, and for running a Moru runner inside a job of another CI system while you move a repository over.

It exits with 0 whether or not a job came and however the job ended, since the result is on the node. That includes a job this runner is too old to read: the node marks it failed, saying to upgrade moru-runner. It exits with an error when it can’t reach the node or the node refuses it. --max-jobs is ignored.

moru-runner run --once --kind ci

Only named jobs#

With --only-named, the runner takes a CI job only when the job names it, with runs-on: { runner: <name> } or, in a GitHub workflow, a runs-on label equal to its name, and only when the run comes from a push or a manual start. It never takes a change’s runs, whose workflow file the change itself may have written, and no agent jobs. Scheduled runs it takes only when also started with --schedules: a schedule runs whatever the default branch holds, so anyone who can change that branch decides what runs there. It’s for a runner that holds deploy secrets, or whose caches later runs must be able to trust. It can’t be combined with --kind implement or --kind review.

moru-runner run --only-named --cache-dir /var/lib/moru-deploy

At start it says what it takes. The node does the choosing; the runner checks again and fails a job that isn’t a CI job, comes from a change, is a scheduled run without --schedules, or doesn’t name it. It knows its own name when it was registered with moru-runner register; started with --token, it can’t check the name and says so at start. Run no other runner under the same user on that machine: see Deploy runners.

Containers#

CI jobs with container:, services: or Docker actions run them with a container engine’s command line (see Containers). A runner that takes CI jobs looks for one when it starts: the CLI --container-cli names, else docker, then podman, on its PATH. It runs <cli> version --format '{{json .}}' (10 seconds at most) and needs an answer from a server that runs Linux containers. Until it gets one, it tells the node it can’t run containers, so such jobs go to the person’s other runners or wait. Its log says which it is:

containers on: docker 29.8.2 (/usr/local/bin/docker)
containers off: <why>; jobs with container, services or Docker actions go to other runners (probed again every few minutes)

It asks again every 5 minutes, and before it asks for work after a failed check, so an engine started later is picked up without a restart. With --container-cli none it never asks, and says “containers off: turned off (—container-cli none); jobs with container, services or Docker actions go to other runners”. Use that on a runner that has Docker but shouldn’t run CI containers.

Everything the runner creates is labelled moru.runner (from its DID), moru.job and moru.host (this machine), and named moru-<job>-<role>, where <job> is the first 12 characters of the job’s ID and the role is job, svc-<id> or act-<n>. A job’s containers and network are removed when it ends, however it ends. The first time the engine answers after the runner starts, the runner removes the containers and networks labelled with its own ID that no running job owns, which is what a runner that was killed leaves. Images it built for Docker actions (moru-action:<commit>-<hash>) are removed with its copy of the action, after 7 unused days.

A registry login (credentials) goes to a temporary configuration in the job’s folder, the password through stdin, never on the command line. Variables reach a container through a private --env-file (in a folder next to the job’s, which no container mounts) or the CLI’s own environment, never as -e NAME=value.

The docker or podman command starts from an empty environment plus what the engine needs: PATH, HOME, USER, LOGNAME, TMPDIR, SHELL, LANG and LC_*, DOCKER_*, BUILDKIT_*, BUILDX_*, BUILDAH_*, COMPOSE_*, CONTAINER_HOST, CONTAINER_CONNECTION, CONTAINER_SSHKEY, CONTAINER_PASSPHRASE, CONTAINERS_*, PODMAN_*, STORAGE_DRIVER, STORAGE_OPTS, REGISTRY_AUTH_FILE, XDG_*, DBUS_SESSION_BUS_ADDRESS, SSH_AUTH_SOCK, SSL_CERT_FILE, SSL_CERT_DIR and the proxy variables. So a container can’t get the runner’s token, its ci.toml secrets or model API keys, whatever its options say. A credential helper that needs another variable has to read it from a file.

Stopping#

Ctrl-C or SIGTERM stops taking jobs and lets the running ones finish. A second signal cancels them and still cleans up their working copies and containers. A third exits at once; the containers it leaves are removed the next time the runner starts.

ci run#

Runs a workflow’s jobs, or one job, in the current checkout, without a node. It reads the workflow from .moru/workflows/ in the working tree, or from .github/workflows/ when the first has none, and runs the steps there, as you, with your environment and tools: uncommitted changes are included, and whatever a step changes stays changed. No node, token or runner key is used, and nothing is signed or reported. runs-on is ignored: every job runs on this machine. See CI and the CI file reference.

moru-runner ci run [OPTIONS] [TARGET]

TARGET is a workflow (the file name without .yml) or workflow/job. Without one, it lists every workflow/job and the problems in files that don’t parse, and exits with 2. A job of a called workflow is listed and run under its caller, ci/checks/lint; a file whose only trigger is call isn’t a workflow of its own here either.

  • ci run checks runs every job of checks.yml in needs order, one at a time, passing outputs on and skipping the jobs that need a failed job, unless they set when: { always: true }.
  • ci run checks/test runs that job alone. The jobs it needs don’t run, so its MORU_NEEDS_* variables are empty. In a GitHub workflow its needs context is empty too, and its if reads as though they succeeded.

Every matrix combination runs unless --matrix picks some. Jobs’ when: is checked against --event and --ref; a job that doesn’t match is skipped, with a note. The workflow’s on: and paths: aren’t checked. MORU_RUN_ID is local, MORU_COMMIT is HEAD’s commit (empty without one), and MORU_REF is empty when HEAD is detached and there’s no --ref.

A GitHub workflow’s jobs follow the same rules as on a node: a job’s if is checked with needs (each needed job’s result and outputs) and the status functions, and its name, timeout-minutes, continue-on-error and strategy.fail-fast are read as they are there. runs-on isn’t: every job runs here. A job that fails under continue-on-error doesn’t fail the run. --input name=value gives a manual run its inputs, checked against the workflow’s workflow_dispatch inputs (types, required inputs, choices) and filled with their defaults; a native workflow’s job gets them as MORU_INPUT_<NAME>, and a called job gets what its caller passes in with:.

Actions listed in .moru/actions.lock run at their locked commits; others are looked up and fetched into <cache-dir>/actions/. With --offline no action is looked up or fetched: a job that uses an action the lock doesn’t list, or one that isn’t in the cache yet, fails before its first step. Run ci lock, or one run without --offline, to fill the cache. It doesn’t stop the steps themselves from using the network: a run step, actions/checkout with submodules or lfs, or jdx/mise-action installing tools.

Caches are kept in <cache-dir>/ci-cache/ with the size ci.toml’s [cache] sets. A local run saves into a scope of its own, local:<ref>, which a runner’s jobs never read, so uncommitted work can’t reach them even with a runner’s --cache-dir. It restores from that scope first, then from the branch’s and the default branch’s, as a runner’s job would. A cache never holds the runner’s own .runner/ folder or other repositories’ caches, even for a path of ~.

Artifacts go to <cache-dir>/ci-artifacts/<workflow>-<time>/, and the run prints that folder at the end; a job that needs another finds its artifacts in $MORU_ARTIFACTS as on a runner. As on a runner, a symbolic link in the checkout that points outside it is left out of an artifact, with a warning that names the link. dorny/paths-filter has no changed files to look at, so every filter is true.

Jobs with container:, services: or Docker actions use the engine --container-cli names, else docker, then podman. It’s looked for when a job first needs it. Without one, such a job fails before its steps and says why; other jobs run as usual. Images are pulled for each job, and one already here is used if the pull fails; with --offline, nothing is pulled and a missing image fails the job, naming it. Your working tree and the run’s temporary folder are mounted into a job container at their own paths, so on a Mac they must be in folders your engine shares. What a run creates is labelled with its process ID and removed when the job ends. On Ctrl-C the run stops the steps, then removes its containers (it says so, and can take up to 75 seconds); a second Ctrl-C quits at once and leaves them, and the next ci run that uses containers removes what earlier runs left on this machine, sparing runs still going. A run counts as going while a process with its ID is alive on the machine that started it (the moru.host label, from the machine ID). Two machines that share a machine ID and one engine could each take the other’s process IDs for their own.

Each job’s result is printed when it ends, and a summary of all of them at the end.

FlagVariableDefault
--matrix <KEY=VALUE>Run only the combinations with this value (repeatable). Jobs without the key run as usual.
--event <EVENT>push (manual with --input)push, change, manual or schedule: MORU_TRIGGER, github.event_name, and what when: and if see. schedule needs a workflow with a schedule.
--input <NAME=VALUE>A manual input (repeatable), checked and typed against the workflow’s manual trigger.
--offlineLook up and fetch no action: run only actions in .moru/actions.lock that are already in the cache. Pull no image (with docker, building a Docker action’s Dockerfile may still fetch its base image; podman builds with --pull=never). The steps themselves may still use the network.
--ref <REF>the current branchMORU_REF, and a change’s target with --event change. A full ref, or a branch name.
--repo <OWNER/NAME>from the origin remote’s URLMORU_REPO, and the repository --secrets is scoped to.
--secretsGive jobs the secrets they list from ci.toml, where its scopes allow them for this repo, ref and event. Without it, a job that lists a secret fails.
--ci-config <CI_CONFIG>MORU_CI_CONFIG<cache-dir>/.runner/ci.tomlThe ci.toml that --secrets reads (it must exist then), and the cache size, which is read without --secrets too.
--cache-dir <CACHE_DIR>your user cache directoryWhere ci.toml, fetched actions, caches and artifacts are: ~/Library/Caches/moru-runner on macOS, else $XDG_CACHE_HOME/moru-runner or ~/.cache/moru-runner. Never the checkout.
--actions-url <URL>MORU_ACTIONS_URLhttps://github.comWhere actions are fetched from, as for run.
--container-cli <CLI>MORU_CONTAINER_CLIdocker, then podmanThe container engine, as for run; none makes jobs that need one fail before their steps.

Steps get your environment without MORU_RUNNER_TOKEN, MORU_TOKEN and the model credentials. With --secrets, the variables ci.toml reads secrets from are removed too, and secret values are replaced with [redacted] in everything it prints. Without --secrets, only ci.toml’s [cache] section is read.

Exit status:

Status
0Every job that ran passed.
otherThe first failed job’s exit code, in the order jobs ran (1 if it has none, such as a missing secret or an action --offline refused). A job under continue-on-error doesn’t count.
124A job ran past its timeout.
128 + signalCtrl-C (130), SIGTERM (143) or SIGHUP (129). The running step’s processes are killed first.
2No target, not in a git repository, no workflow files, an unknown workflow, job or matrix value, a wrong --input, or a workflow that doesn’t parse (path:line:col: message).
moru-runner ci run checks/test --matrix toolchain=stable
moru-runner ci run checks --event change --ref main
moru-runner ci run deploy --secrets --repo acme/timetable
moru-runner ci run release --input version=1.4.0 --input dry-run=true
moru-runner ci run checks --offline

ci lock#

Writes .moru/actions.lock: the commit and tree of every action your workflows use, so the node runs them at those commits. Run it in your checkout and commit the file.

moru-runner ci lock [--check] [--cache-dir <CACHE_DIR>] [--actions-url <URL>] [--container-cli <CLI>]

It reads the same workflows as ci run (.moru/workflows/, else .github/workflows/, with the workflows they call included), looks up each uses: owner/repo[/path]@ref, fetches it, and follows the actions that composite actions use, up to 10 deep. Built-in replacements, actions Moru refuses and local ./path actions get no entry, but the actions a local action uses do. A workflow Moru won’t run still has its actions locked, with a note. A uses: pinned to a full commit is locked at that commit. Entries are sorted and written as the workflow spells them; one whose ref still points at the same commit stays as it was. It prints one line per action:

actions/setup-node@v4 → 1a2b3c4 (tree 5d6e7f8)

Images get their digest. Each uses: docker://<image> gets an entry of its own, and a Docker action whose runs.image is docker://… gets the image’s digest in its entry. ci lock pulls the image with the engine --container-cli (MORU_CONTAINER_CLI) names, else docker, then podman, and asks it for the digest; an image pinned with @sha256:… needs no pull. Without an engine, the entry is written without a digest, with a note that says so:

docker://koalaman/shellcheck:v0.10.0 → sha256:6e6f1a…

With --check, it writes nothing and lists what the lock is missing or has stale (a ref that now points at another commit, an image whose digest changed, or an entry no workflow uses), for a CI step or a pre-commit hook. --cache-dir is where fetched actions are kept (default: as for ci run), and --actions-url (MORU_ACTIONS_URL) where they come from (default https://github.com; a mirror, or a directory of <owner>/<repo>.git repos).

Exits 0 when done (with --check, when the lock is up to date), 1 when an action can’t be looked up or fetched or --check found problems, and 2 when it isn’t run in a git repository, there are no workflows, or a workflow in .moru/workflows/ doesn’t parse.

ci import#

Writes the native equivalent of the GitHub workflows in .github/workflows/ into .moru/workflows/, with a # TODO: comment at everything that has no native form. See Moving to Moru’s format for what maps and what doesn’t.

moru-runner ci import [--force] [--flatten] [FILE...]

FILE is a workflow to import: a path, or a name in .github/workflows/ (ci or ci.yml). It must be a file directly in .github/workflows/ of the checkout you run it in. Without one, every workflow there is imported. A job that calls a reusable workflow of the repository still calls it, as uses: ./.moru/workflows/<name>.yml, and the reusable workflow is written with a call trigger. A calling file imported without the file it calls gets a warning that names the command to import it.

Each workflow becomes .moru/workflows/<same name>.yml, with the same job IDs. Before it writes a file, ci import reads it back with the native reader; if that fails, it’s a bug in the import, and nothing is written. It writes only inside .moru/workflows/ of this checkout, never through a symbolic link, and refuses a .moru or .moru/workflows that’s a link. It prints one line per file, with its jobs and TODOs, and with --flatten, every required-job name that changes because a reusable workflow’s jobs moved into the calling file:

.github/workflows/ci.yml → .moru/workflows/ci.yml: 3 jobs, 2 TODOs

Once .moru/workflows/ has a file, .github/workflows/ no longer runs on Moru, so it warns about the workflows it didn’t import.

Flag
--forceOverwrite files that are already in .moru/workflows/.
--flattenWrite the jobs of reusable workflows into the files that call them instead of keeping the calls. A file whose only trigger is workflow_call isn’t written then.

Exits 0 when it wrote a file, 1 when it wrote none (they exist without --force, or none could be imported), and 2 when it isn’t run in a git repository, there are no workflows, or a FILE isn’t a workflow in .github/workflows/.

CI secrets#

A runner gives CI jobs the secrets in its ci.toml: <cache-dir>/.runner/ci.toml, or the file --ci-config names. The node gets each secret’s name and scope, never its value. The runner reads values when a job needs them, so a changed file or variable is picked up without a restart.

[secrets.REGISTRY_TOKEN]
env = "REGISTRY_TOKEN"              # the runner's variable that holds it
repos = ["acme/timetable"]
refs = ["refs/heads/main", "refs/tags/v*"]
triggers = ["push", "manual"]

[secrets.NPM_TOKEN]
file = "~/.config/moru/npm-token"   # or a file
repos = ["acme/*"]

Each [secrets.NAME] is one secret. NAME is what jobs list in secrets: and the variable the step gets: letters, digits and _, not starting with a digit.

KeyDefault
envThe runner’s environment variable that holds the value. Give env or file, not both.
fileA file that holds the value; trailing newlines are dropped. ~/ is your home directory; a relative path is relative to ci.toml’s directory. It must exist when the runner starts.
reposRequired. The repositories it’s given to, as owner/name patterns: acme/* for all of an owner’s repositories. Each must contain /.
refsany refFull refs it’s given for, as patterns starting with refs/ or *: refs/heads/main, refs/tags/v*. For a change’s run, the ref is the change’s target branch.
triggerspush, manualThe runs it’s given to: change, push, manual, schedule. A change’s code hasn’t been reviewed, so a secret goes to change runs only if you list change. Scheduled runs start with no one, from whatever the default branch holds, so a secret goes to them only if you list schedule.
approved_runsfalseReserved for runs a maintainer approves for someone without write access, which later versions add.

A runner leases a CI job only if every secret the job lists is in ci.toml with a scope that matches the job’s repository, ref and trigger; otherwise the job waits for another of the person’s runners, and the run page names the missing secret. The runner checks again before the job starts, and fails it if a value can’t be read or is empty.

Unknown keys are errors, so a typo like ref for refs can’t widen a scope. The runner doesn’t start if ci.toml has an error; the message names the secret and never echoes a value. It warns at start, naming only paths and secret names, when ci.toml or a secret’s file can be read by other users, when an env variable isn’t set, and when a value is shorter than 4 characters (too short to redact reliably).

ci.toml isn’t read by a runner that doesn’t take CI jobs. Variables that env names are removed from every step’s environment, so a job sees only the secrets it lists. Values, and each line of a multi-line value 8 characters or longer, are replaced with [redacted] in logs and outputs.

Scopes decide what a job is given, not what it can reach: see Where to run a runner.

CI caches#

CI caches (a job’s cache:, or actions/cache in a GitHub workflow) live in <cache-dir>/ci-cache/<owner>/<repo>/, on this runner only. ci.toml sets how much room they may take:

[cache]
max_size = "20GiB"

max_size is a size with a unit (500MB, 1.5 GiB; KB, MB, GB, TB count in thousands, KiB, MiB, GiB, TiB in 1,024s) or a number of bytes. The default is 10 GiB. Past it, the entries used least recently are removed; entries not used for 7 days are removed anyway. An entry larger than max_size isn’t saved. [cache] is read even without secrets in the file, and unknown keys in it are errors.

Which runs restore which entries is in Caches. Every job on the runner can write to these files directly, so a change’s job can tamper with what later runs restore. On a runner whose caches must be trusted, use --only-named.

key#

Prints the runner’s DID, creating its key on first use. For registering a runner from the node’s shell with moru-node create-runner-token <name> --key <DID> --owner <user>.

moru-runner key [OPTIONS]
FlagDefault
--cache-dir <CACHE_DIR>./runner-cacheWhere the key lives.
--key-file <KEY_FILE><cache-dir>/.runner/runner.keyThe key file.
moru-runner key --cache-dir /var/lib/moru-runner

The cache directory#

--cache-dir (default ./runner-cache, relative to where you start the runner) holds:

  • .runner/runner.key: the runner’s signing key. Keep it private; it’s how the node knows the runner.
  • .runner/token.json: the token register saved.
  • .runner/ci.toml: the secrets the runner gives CI jobs, if you wrote one.
  • the object cache: a copy of each repo the runner has worked on, so jobs start without cloning everything again.
  • actions/: the actions CI jobs fetched, one copy per commit. A copy unused for 7 days is removed, along with the images built from its Dockerfiles. A job’s container sees this folder read-only.
  • ci-cache/: CI caches, see CI caches.
  • each running job’s own folder, removed when the job ends, and an agent job’s working copy in it.
  • .runner/work/: CI jobs’ checkouts, unless --work-dir puts them elsewhere. See The work directory.

Use one cache directory per runner, and pass the same one to every command.

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