magus v0.3.0 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
4 min read

Configuration

magus resolves configuration from three layers, highest precedence first: a CLI flag, a MAGUS_* environment variable, then the magus.yaml file at the workspace root. This page is the complete inventory of config keys, each with its magus.yaml path, environment variable, CLI flag, and value type.

cache

Config key Environment variable Flag Type
cache.dir MAGUS_CACHE_DIR --cache-dir string
cache.immutable MAGUS_CACHE_IMMUTABLE --cache-immutable bool
cache.remote.insecure MAGUS_CACHE_REMOTE_INSECURE --cache-remote-insecure bool
cache.remote.trusted_keys MAGUS_CACHE_REMOTE_TRUSTED_KEYS (env only) list (comma-separated, env only)
cache.size_mb MAGUS_CACHE_SIZE_MB --cache-size-mb int

ci

Config key Environment variable Flag Type
ci.max_shards MAGUS_CI_MAX_SHARDS --ci-max-shards int
ci.runner_pool_budget MAGUS_CI_RUNNER_POOL_BUDGET --ci-runner-pool-budget int

console

Config key Environment variable Flag Type
console.enabled MAGUS_CONSOLE_ENABLED (env only) bool (env only)
console.url MAGUS_CONSOLE_URL --console-url string

daemon

Config key Environment variable Flag Type
daemon.address MAGUS_DAEMON_ADDRESS --daemon-address string
daemon.enabled MAGUS_DAEMON_ENABLED --daemon-enabled bool
daemon.idle_ttl MAGUS_DAEMON_IDLE_TTL --daemon-idle-ttl duration
daemon.maintenance.rotate_activities MAGUS_DAEMON_MAINTENANCE_ROTATE_ACTIVITIES --daemon-maintenance-rotate-activities duration
daemon.maintenance.rotate_logs MAGUS_DAEMON_MAINTENANCE_ROTATE_LOGS --daemon-maintenance-rotate-logs duration
daemon.maintenance.sync_graph MAGUS_DAEMON_MAINTENANCE_SYNC_GRAPH --daemon-maintenance-sync-graph duration
daemon.socket MAGUS_DAEMON_SOCKET --daemon-socket string
daemon.workspaces MAGUS_DAEMON_WORKSPACES (env only) list (comma-separated, env only)

general

Config key Environment variable Flag Type
concurrency MAGUS_CONCURRENCY -j, --concurrency int
default_charms MAGUS_DEFAULT_CHARMS (env only) list (comma-separated, env only)
dry_run MAGUS_DRY_RUN -u, --dry-run bool
history_path MAGUS_HISTORY_PATH --history-path string
target_timeout MAGUS_TARGET_TIMEOUT --target-timeout duration

graph

Config key Environment variable Flag Type
graph.depth MAGUS_GRAPH_DEPTH --graph-depth int
graph.direction MAGUS_GRAPH_DIRECTION --graph-direction string
graph.roots MAGUS_GRAPH_ROOTS --graph-roots string
graph.spell MAGUS_GRAPH_SPELL --graph-spell string

hints

Config key Environment variable Flag Type
hints.enabled MAGUS_HINTS_ENABLED (env only) bool (env only)

knowledge

Config key Environment variable Flag Type
knowledge.max_size_mb MAGUS_KNOWLEDGE_MAX_SIZE_MB --knowledge-max-size-mb int
knowledge.symbol_indexing.disabled MAGUS_KNOWLEDGE_SYMBOL_INDEXING_DISABLED --knowledge-symbol-indexing-disabled bool
knowledge.symbol_indexing.min_interval_seconds MAGUS_KNOWLEDGE_SYMBOL_INDEXING_MIN_INTERVAL_SECONDS --knowledge-symbol-indexing-min-interval-seconds int
knowledge.symbol_indexing.quiet_seconds MAGUS_KNOWLEDGE_SYMBOL_INDEXING_QUIET_SECONDS --knowledge-symbol-indexing-quiet-seconds int
knowledge.vcs.authorship MAGUS_KNOWLEDGE_VCS_AUTHORSHIP (env only) bool (env only)
knowledge.vcs.enabled MAGUS_KNOWLEDGE_VCS_ENABLED --knowledge-vcs-enabled bool
knowledge.vcs.max_commits MAGUS_KNOWLEDGE_VCS_MAX_COMMITS --knowledge-vcs-max-commits int
knowledge.workspaces MAGUS_KNOWLEDGE_WORKSPACES (env only) list (comma-separated, env only)

log

Config key Environment variable Flag Type
log.format MAGUS_LOG_FORMAT --log-format string
log.level MAGUS_LOG_LEVEL --log-level string
log.silent MAGUS_LOG_SILENT (env only) bool (env only)
log.stream MAGUS_LOG_STREAM (env only) bool (env only)

mcp

Config key Environment variable Flag Type
mcp.address MAGUS_MCP_ADDRESS --mcp-address string
mcp.enabled MAGUS_MCP_ENABLED (env only) bool (env only)

report

Config key Environment variable Flag Type
report.filter MAGUS_REPORT_FILTER (env only) list (comma-separated, env only)

sandbox

Config key Environment variable Flag Type
sandbox.enabled MAGUS_SANDBOX_ENABLED --sandbox-enabled bool
sandbox.env.passthrough MAGUS_SANDBOX_ENV_PASSTHROUGH (env only) list (comma-separated, env only)

telemetry

Config key Environment variable Flag Type
telemetry.enabled MAGUS_TELEMETRY_ENABLED --telemetry-enabled bool
telemetry.endpoint MAGUS_TELEMETRY_ENDPOINT --telemetry-endpoint string
telemetry.insecure MAGUS_TELEMETRY_INSECURE --telemetry-insecure bool
telemetry.protocol MAGUS_TELEMETRY_PROTOCOL --telemetry-protocol string
telemetry.sample_ratio MAGUS_TELEMETRY_SAMPLE_RATIO --telemetry-sample-ratio float
telemetry.service_name MAGUS_TELEMETRY_SERVICE_NAME --telemetry-service-name string

vcs

Config key Environment variable Flag Type
vcs.base_ref MAGUS_VCS_BASE_REF --vcs-base-ref string
vcs.enabled MAGUS_VCS_ENABLED (env only) bool (env only)
vcs.name MAGUS_VCS_NAME --vcs-name string

volatility

Config key Environment variable Flag Type
volatility.annotate_gha MAGUS_VOLATILITY_ANNOTATE_GHA --volatility-annotate-gha bool
volatility.bootstrap_samples MAGUS_VOLATILITY_BOOTSTRAP_SAMPLES --volatility-bootstrap-samples int
volatility.enabled MAGUS_VOLATILITY_ENABLED --volatility-enabled bool
volatility.min_samples MAGUS_VOLATILITY_MIN_SAMPLES --volatility-min-samples int
volatility.threshold MAGUS_VOLATILITY_THRESHOLD --volatility-threshold float
ReferencePages in this section. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. StatusServiceStatusService serves the snapshot, and streams it for a live dashboard.
auto-generatedconfigmagus.yamlconfigurationenvironment variablesflagsreference
Last updated (3e1b75ad)
Earlier changes on this page (2)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. See services.

Daemon

The background magus host that owns shared state such as services and the warm knowledge graph. See daemon.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Pool

The concurrency pool: the shared set of slots that caps how many targets run in parallel on one machine. Its capacity defaults to MAGUS_CONCURRENCY, then 4 on GitHub-hosted runners, then min(NumCPU, 8); magus status and the dashboard report it live. See daemon.

Concurrency

How many targets run at once. It is bounded by the pool's capacity and set with --concurrency, MAGUS_CONCURRENCY, or the concurrency config key. See daemon.

Volatility

A target that fails once and passes on rerun is volatile, as opposed to a regression that started failing and stays failing. magus keeps per-target pass/fail history and a Wilson-score volatility rate to tell them apart and auto-retry the noise. See volatility.

Conventions

Documentation conventions

A few conventions run through every page on this site. This page is the key.

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.

Command synopsis notation

Every synopsis on this site and in magus <verb> -h and the manpages uses the same five marks. This is the whole vocabulary:

notation means example
<value> required; replace it magus run <target>
[thing] optional; omit the brackets if you use it magus ls [flags]
<a|b|c> required, and one of these exact words magus completion <bash|zsh|fish|powershell>
<value>... repeatable; one or more, space separated magus describe file <path> [<path>...]
word[s] the s is optional - both spellings work magus describe spell[s]

The last one is the only place square brackets do NOT mean "optional argument": spell[s] means magus describe spell and magus describe spells are the same command, not that s is a separate thing you can pass.

Combining them reads left to right, so [<path>...] is "optional, and if you give it, one or more paths":

magus run <target> [flags] [project...]
magus describe file <path> [<path>...] [flags]

[flags] and [args] are categories rather than placeholders - there is nothing called "flags" to substitute. Run the command with -h to see which it accepts.

A bare -- ends magus's own arguments; everything after it is passed through untouched to whatever the target runs:

magus run test libs/foo -- -run TestX

Values are written --flag <value> in synopses, but every magus flag also accepts --flag=<value>, -flag <value> and -flag=<value>. Pick whichever reads better; they parse identically.

Some flags take a comma-separated list, which is written as one value. Spaces around the commas are trimmed and empty entries are ignored:

magus status --probe=mcp,liveness

A few take a structured value spelled key=<value> pairs, comma separated. Where a pattern is accepted it is always the same three types:

magus watch --ignore type=glob,pattern='**/node_modules/**'
magus where --filter type=regex,pattern='^libs/'

Shell commands

Command blocks omit the shell prompt - copy the whole block as-is, no leading $ or > to strip. A # comment on or after a line shows expected output or an aside:

magus version
# magus 0.4.2

Windows examples are shown in PowerShell and labelled as such.

Reading Buzz: the backslash

Buzz code on this site is full of names like fs\readFile and magus\project. The backslash is namespace access - it reaches into a module. Most languages spell this with a dot, so it is the one piece of syntax worth knowing before you read anything else here.

Buzz uses both separators, and the distinction is what they reach into:

final body = fs\readFile("VERSION");   // backslash: a function IN the fs module
ctx.needs(build);                      // dot: a method ON the ctx value

Backslash reaches into a module; dot reaches into a value you already have. So os\exec is the exec function the os module provides, while site.docPages is a field on the site object. A module name never appears on the left of a dot, and a variable never appears on the left of a backslash.

The full module list is the standard library reference.

Runnable examples

Some Buzz code blocks are live: a Run button appears in the corner and executes the snippet in the in-browser playground via WebAssembly - no install needed. Blocks without the button are illustrative only. (With JavaScript off, every block is plain, copyable text.)

Admonitions

Call-outs are rendered from GitHub-style alert blockquotes and carry a colored accent per type:

Note

Context worth knowing, but not a warning.

Warning

Something that can bite you if ignored.

The types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

Footnotes

An aside that would break the flow inline is written as a footnote: a bracketed superscript like this1 links to a short note at the foot of the page, which links back. The generated module reference uses them to flag methods that also exist in Buzz's own standard library without cluttering each signature.

Reach for a footnote when a sentence needs a source, a caveat, or a pointer that would derail it inline: a citation or external reference, an edge case that qualifies the claim, or a "see also" that is worth keeping but not worth interrupting the thought. Prefer a footnote over a parenthetical that runs long, and over dropping the detail entirely.

Code-block titles

A fenced block can carry a filename or label in a small caption bar above it, so you know which file a snippet belongs in (for example a magusfile.buzz).

Diffs

A ```diff block shows a change: added lines (leading +) render as a green band, removed lines (leading -) as a red one.

 export fun ci(ctx: magus\Context, args: [str]) > void {
-    ctx.needs(lint);
+    ctx.needs(lint, test);
 }

Auto-generated pages

Pages built from source - the module reference, the spell reference, the man pages, and the configuration reference - carry an auto-generated chip. Edit the generator, not the page; a hand edit is overwritten on the next build.

Reading time

Longer pages show an estimated reading time near the top. It is a word count of the source, not a tracker - nothing is measured about you.

  1. Authored as text[^label] in the prose, with a matching [^label]: note line anywhere in the file. ↩︎