Runner configuration

Files and directories

The runner follows the XDG base directories.

Directory	Default	Override	Holds
Config	`~/.config/minga`	`MINGA_CONFIG_DIR`, else `$XDG_CONFIG_HOME/minga`	`runner.toml`, `credentials`, `ceiling.toml`, pinned release-signing keys
State	`~/.local/state/minga`	`MINGA_STATE_DIR`, else `$XDG_STATE_HOME/minga`	`runner.log`, the control socket `runner.sock`, the local run journals, the service’s stdout and stderr logs
Data	`~/.local/share/minga`	`MINGA_DATA_DIR`, else `$XDG_DATA_HOME/minga`	`worktrees/`: one git worktree per item

The runner creates these directories with mode 0700 and writes its config files with mode 0600.

File	What it is
`runner.toml`	Settings, the pairing, profiles and repos. Written by `minga`; edit with care.
`credentials`	The runner’s token for its pairing. Mode `0600`, never in `runner.toml`, never logged. Keep it private; revoke the runner in the app if it leaks.
`ceiling.toml`	The on-device policy ceiling (below).
`runner.log`	The runner’s log, in logfmt.

runner.toml

# Minga runner settings (format 2), written by `minga`. Edit with care.
# The runner token lives in ./credentials (mode 0600), never in this file.

[runner]
name = "my-mac"
capacity = 4

[[pairing]]
server = "https://app.minga.run"
workspaceId = "<workspace id>"
workspaceName = "Acme"
runnerId = "<runner id>"
rpcUrl = "wss://app.minga.run/api/runners/rpc"
connectUrl = "<legacy socket url>"

[[profiles]]
id = "claude-personal"
agent = "claude"
home = "~/.claude"
default = true

[[profiles]]
id = "codex-personal"
agent = "codex"
home = "~/.codex"
default = true
accessMode = "ask"

[[repos]]
path = "~/code/dictly"
remote = "github.com/acme/dictly"

`[runner]`

Key	Default	Meaning
`name`	the host name	The runner’s name in the app
`capacity`	`4`	How many runs at once, 1 to 32
`autoUpdate`	`true`	Install new signed releases on its own when idle

`[[pairing]]`

One entry: one machine is paired with one workspace. Written by minga runner login, removed by minga runner logout. Don’t edit it by hand.

`[[profiles]]`

On its first start, the runner adds a profile for each of these homes that exists: ~/.claude (as claude-personal) and ~/.codex (as codex-personal).

Key	Default	Meaning	Set with
`id`	required	Lowercase letters, digits and `-`, at most 40 characters	`profile add --id`
`agent`	required	`claude` or `codex`	`profile add`
`home`	required	The CLI home (`CLAUDE_CONFIG_DIR` or `CODEX_HOME`)	`profile add --home`
`default`	`false`	The profile a run uses for this CLI when it names none	`profile add --default`
`workspaces`	every workspace	The workspace ids this profile serves; `[]` serves none	`profile add --workspaces`, `profile scope`
`enabled`	`true`	A disabled profile takes no runs	the app
`capacity`	the runner’s capacity	Runs at once on this profile, 0 to 16	the app
`cliPath`	from `PATH`	The CLI binary	`profile add --cli-path`
`accessMode`	`auto`	`auto`, `ask` or `full`	`profile set <id> access`
`mcp`	`cli`	`cli` (the CLI’s own MCP servers plus Minga’s) or `minga_only`	`profile set <id> mcp`
`mcpApproval`	`approve`	In Auto: `approve` (MCP tools run without asking) or `ask`	`profile set <id> mcp-approval`
`autoNetwork`	`true`	Codex in Auto: network in the sandbox	`profile set <id> network`
`modelOverride`	the CLI’s default	The model for runs that name none	`profile set <id> model`
`effortOverride`	the CLI’s default	`low`, `medium`, `high` or `max`, for runs that name none	`profile set <id> effort`
`codexReasoningSummary`	`concise`	What Codex shows of its reasoning: `none`, `auto`, `detailed`, `concise`, or `inherit` (pass nothing)	by hand
`claudePermissionMode`	from the access mode	Override: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `dontAsk`, `auto`	`profile cli --claude-permission-mode`
`claudeSandbox`	not passed	Override: Claude Code’s sandbox on or off	`profile cli --claude-sandbox`
`codexSandbox`	from the access mode	Override: `read-only`, `workspace-write`, `danger-full-access`	`profile cli --codex-sandbox`
`codexApprovalPolicy`	from the access mode	Override: `untrusted`, `on-request`, `never`	`profile cli --codex-approval-policy`

What each access mode passes to each CLI is in Access modes.

`[[repos]]`

Key	Meaning
`path`	The clone’s top-level directory
`remote`	Its normalized `origin` remote

Written by minga repo add, removed by minga repo remove. Clones the runner finds on its own are never written here.

Settings from the app

If you own the runner, Settings › Runners in the app can change its capacity, auto-update, and each profile’s enabled switch, capacity, access mode and the other profile settings. The runner checks each change and writes it to runner.toml. An invalid value refuses the whole change. Nobody else can configure your runner.

ceiling.toml: the policy ceiling

A limit on the machine that only you can raise, on the machine. The cloud sees only a summary and its hash. It is created with these defaults:

maxPermission    = "workspace_write"
allowComputerUse = false
allowRunKinds    = ["turn", "worker", "validator"]
allowedAgents    = ["claude", "codex"]
repos            = "registered"

Key	Values	Meaning
`maxPermission`	`read_only`, `workspace_write`	The most a run on this machine may get
`allowComputerUse`	`false`	Not supported yet
`allowRunKinds`	`turn`, `worker`, `validator`	Which kinds of runs this machine takes: agents’ turns, workers, validators
`allowedAgents`	`claude`, `codex`	Which CLIs it runs
`repos`	`registered`, `none`	`registered`: the clones this runner serves (registered and found); `none`: no repo at all

If the file cannot be read or is invalid, the runner allows nothing until you fix it.

Environment variables

The runner reads:

Variable	Meaning
`MINGA_CONFIG_DIR`, `MINGA_STATE_DIR`, `MINGA_DATA_DIR`	Move the config, state or data directory
`XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `XDG_DATA_HOME`	Used when the `MINGA_*` variables are not set
`HOME`	The home directory everything else is relative to
`PATH`	Where it finds `claude`, `codex`, `git` and `gh` (the service keeps the one from install time)

For each run, the runner sets CLAUDE_CONFIG_DIR or CODEX_HOME to the profile’s home.

The install script (curl -fsSL https://app.minga.run/install.sh | sh) reads:

Variable	Default	Meaning
`MINGA_VERSION`	latest	Install this version
`MINGA_INSTALL_DIR`	`~/.local/bin`	Where to put the binary
`MINGA_BASE_URL`	`https://app.minga.run`	Where to download from
`MINGA_VERIFY_SIGNATURE`	`auto`	`auto`: verify the Ed25519 release signature when an OpenSSL with Ed25519 is available, else warn and rely on the SHA-256 check; `require`: refuse to install without a verified signature
`MINGA_OPENSSL`	the first that passes a self-test	The `openssl` binary to verify with (macOS’s LibreSSL lacks Ed25519; Homebrew’s `openssl@3` is found automatically)

Service files

minga runner install --print shows the file without installing it.

macOS: LaunchAgent

~/Library/LaunchAgents/run.minga.runner.plist, label run.minga.runner, loaded into your login session (gui/<uid>) so the CLIs see your Keychain logins.

runs minga runner start --foreground;
environment: your PATH at install time, HOME, MINGA_SUPERVISED=launchd, and any MINGA_*_DIR you had set;
RunAtLoad and KeepAlive: starts at login, restarts when it stops (at most every 10 seconds);
output to ~/.local/state/minga/runner.stdout.log and runner.stderr.log.

Linux: systemd user unit

~/.config/systemd/user/minga-runner.service, enabled and started with systemctl --user enable --now.

[Unit]
Description=Minga runner
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart="<path to minga>" "runner" "start" "--foreground"
Environment="PATH=…"
Environment="MINGA_SUPERVISED=systemd"
Environment="HOME=…"
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Logs: journalctl --user -u minga-runner.service, plus ~/.local/state/minga/runner.log. Run sudo loginctl enable-linger $USER to keep it up while you are logged out.

What the runner checks, and when

Check	When
Profiles: signed in, models, usage	At start, every 10 minutes, and when you change a profile
Repos: default branch, read and push access, `gh`	At start, on `minga repo add`, and every 6 hours
Clones in your Claude Code and Codex sessions	After each profile check
New releases (when `autoUpdate` is on)	5 minutes after start, then every 6 hours, and when Minga announces one; installed only while no run is active

Claude Code is a trademark of Anthropic; Codex of OpenAI. Minga is not affiliated.

Privacy Imprint Terms