Runmoor Configuration
Version note: Runmoor 0.2.0 introduced automatic setup and managed runner updates. Guided creation of a new Mac VM during
initis in the next release. Version 0.1.3 uses the explicit pinned configuration and manual image preparation also documented below. Checkrunmoor versionbefore using release-specific commands.
init creates the minimal configuration described below. Existing files are never overwritten. All commands accept --config PATH. Run doctor from another terminal after the manager has prepared its images.
Both supported operating systems use:
State/data may be overridden by absolute TOML paths. Configuration and credential files must be owned by your user, regular files, and mode 0600. Directories/socket are private to that user. Very long state paths exceed the Unix socket length limit and are rejected. Storage relocation requires drain, stop, and a complete installation backup; it is not a live reload.
Recover private configuration access
The setup command is runmoor init, not runmoor config init. Most other
commands, including config validate, status, and service, load the selected
configuration first. init, version, and help can run without an existing
configuration. If the file was removed, restore the original configuration from
a backup before using an existing installation; do not delete its state to make
the error disappear. init creates a new file only when the selected path does
not already exist.
Cannot securely open a private file means a private file could not be opened;
the message does not identify the file or the operating-system error. If
runmoor config validate reports it, inspect the selected configuration path
first. A missing file, an inaccessible path, or a symlink at the file itself
can produce this message. On Ubuntu, inspect the default path with:
If you passed --config PATH, inspect that path instead. Restore a missing
configuration from its matching backup. An existing configuration must be a
regular file owned by the Runmoor user with mode 0600, without a symlink at the
file itself. Changing file permissions cannot restore a missing file.
If configuration validation succeeds but run or status reports the same
message, inspect the configured state directory and its existing files. The
default state location is shown above; [storage].state can override it. A
missing lock or database is normal before the first run because Runmoor creates
those files. Preserve existing state and managed data when diagnosing access.
Create a GitHub PAT
RUNMOOR_PAT is an example environment variable name, not a token issued by
Runmoor. Its value is a GitHub personal access token (PAT) for the repository or
organization in target. Runmoor uses it to request the short-lived runner
credentials; do not substitute a one-hour runner registration token.
In GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Select the repository owner and the repositories this Runmoor connection will manage, then grant:
The token owner must already have access to manage the target's runners.
Organizations may require approval before a fine-grained PAT works. If you use
a classic PAT instead, GitHub documents repo for repository runners and
admin:org for organization runners. Choose an expiration and rotate the token
before it expires. See GitHub's PAT creation guide
and runner authentication permissions.
For a foreground runmoor run, credential = { env = "RUNMOOR_PAT" } reads the
variable from that process's environment. Enter it without putting the value in
shell history:
For a systemd user service on Ubuntu, follow the persistent credential file steps. Exporting the variable in a terminal alone does not pass it to an independently started service.
Automatic configuration
In a terminal, runmoor init asks for the GitHub target, execution backend and
credential reference. On Linux the suggested backend is Docker; on Apple Silicon
macOS it is Tart. Supply the referenced credential separately. Init does not
install Docker/Tart or start a service.
On macOS, interactive Tart setup offers create (the default) or existing.
create downloads the latest host-supported Apple IPSW through Tart or uses
an absolute local .ipsw, supervises guest setup, verifies Guest Agent after
a reboot, seals the image and writes the final configuration. The guest account,
Guest Agent and optional tool setup still require your input. Run runmoor init again with the same config path after an interruption. See Tart image
preparation for the complete first-run steps.
For scripts, provide the inputs directly:
The following generated configuration is for an ARM64 Docker host. It needs no resource limits, architecture, runner version or Docker image digest:
On an amd64 Docker host, init uses x64 instead of ARM64. Tart uses
["runmoor-macos", "macOS", "ARM64"]. These defaults apply only to newly
generated configurations; existing and manually written labels are preserved,
and an omitted labels field stays empty.
The manager detects host capacity and the local Docker engine limit. Defaults
are 2 CPUs/4096 MiB per Docker job and 4 CPUs/8192 MiB per Tart job. Concurrency is
calculated from both CPU and memory, with at most two concurrent Tart VMs.
Smaller machines reduce omitted allocations, down to 1 CPU/1024 MiB for Docker
and 2 CPUs/4096 MiB for Tart. Explicit values are never silently reduced. All
pools, preparation work and DinD share the applicable budgets; warm runners
default to zero. Disk reserves default to 10240 MiB, or 20480 MiB with Tart.
There is no automatic CPU/memory reserve for other applications; set a smaller
[host] budget when sharing the computer with other work.
Releases through 0.2.7 include daemon CPU in DinD reservations. The unreleased DinD CPU admission change counts runner CPU only, keeps combined runner/daemon memory, and preserves the daemon container's CPU limit. Check the containing release before using that calculation; it is not available in 0.2.7.
Omit runner_version, or set it to "latest", for automatic management. An
exact version keeps a pin. Docker image omission chooses the official minimal
image. Explicit custom Docker images still require immutable digests; in latest
mode Runmoor replaces only the dedicated runner directory in a new image.
Language toolchains remain your workflow's responsibility.
Use runmoor config show --resolved and runmoor status to inspect calculated
capacity and the committed runner version. Before the first run, a version can
still be unresolved. These inspection commands do not download images. Use the
runs-on value printed by init in your workflow.
For GitHub App authentication, init accepts --auth app, --client-id,
--installation-id and a credential reference. --credential-file is the
alternative to --credential-env; pass a path or variable name, never a token.
Existing files are never overwritten, and noninteractive init fails with guidance
when required inputs are missing.
To migrate an existing pool, omit its resource/architecture/concurrency fields
where you want automatic defaults and change its runner_version to "latest".
Keep its routing labels and credential references. Keep a custom Docker digest
or omit image to use the official image; retain a Tart image UUID to use it as
the immutable base. Reload after saving. Existing exact version pins continue to
work until you explicitly change them.
Explicit pinned configuration
The complete schema v1 example below is a template: replace image digest placeholders with real immutable images and choose budgets for your host and Docker engine. Pre-pull those images with Docker. A local content-addressed sha256:… image ID is also accepted for images you build yourself.
Use amd64 on an amd64 Ubuntu host. GitHub organization targets omit the repository. Organization pools may set runner_group; repository pools cannot. Pool names and target/group/scale-set identities must be unique. Scale-set names and labels control workflow routing; existing sets without this installation's ownership evidence are never adopted.
For an App connection set auth = "app", client_id, a positive installation_id, and a credential reference to its PEM key. For a file reference use credential = { file = "REPLACE_WITH_ABSOLUTE_PRIVATE_FILE" }. Do not place a PAT or private key in TOML. Service definitions never copy credential values; file references are easier to keep available across login/reboot than environment references.
GitHub App repository registration requires repository Administration read/write and Metadata read; organization registration requires organization Self-hosted runners read/write. GitHub groups and repository access rules remain authoritative.
Unknown keys/schema versions, literal credentials, invalid limits, incompatible architecture, mutable image tags and impossible minimum-idle allocations are rejected. The default preparation limits are five minutes for Docker and ten for Tart; jobs default to six hours. Duration values must be positive and at most seven days.
Optional [storage] fields state and data take absolute user-controlled directory paths. tart_executable and docker_socket are optional top-level executable/socket overrides. The Docker runner path defaults to the official image account home; the Tart path defaults to the actions-runner directory inside the runner account home. Set runner_path explicitly when your compatible image uses another absolute guest path. No shell expansion occurs in TOML.
For App authentication, use the same connection structure with these replacements:
See Docker execution and Tart images for backend requirements.
Explicit macOS host pools
Host execution is unreleased and requires macOS 14+ Apple Silicon. Select it with
runmoor init --backend host; the macOS default remains Tart. Host-only
configurations require no Docker, Tart or Guest Agent. New pools use macos-host,
scale set runmoor-macos-host, and labels runmoor-macos-host, macOS, ARM64.
Authored labels remain unchanged.
Host pools use backend = "host" and plain mode. Omit image, image-source,
runner-path and daemon fields; Runmoor owns each execution path. Image-only setup
is incompatible. timeouts.host_preparation defaults to 5m. Omitted resources
use 2 CPUs/4096 MiB, shrinking to 1 CPU/1024 MiB. Explicit values are never reduced.
Concurrency follows shared CPU/memory budgets without Tart's two-VM limit. These
are admission reservations, not enforced usage limits. Warm capacity defaults to
zero; disk reserve is 10240 MiB unless Tart requires its higher reserve.
Read the host guide for same-account trust, disposable directories, operator toolchains and recovery. Actual host execution, unsigned Xcode builds and live GitHub jobs have not been validated.