magus v0.4.3 is out. See what's new
¶ View generated markdown
5 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.include.arch.enabled MAGUS_CACHE_INCLUDE_ARCH_ENABLED (env only) bool (env only)
cache.include.os.enabled MAGUS_CACHE_INCLUDE_OS_ENABLED (env only) bool (env only)
cache.remote.insecure MAGUS_CACHE_REMOTE_INSECURE --cache-remote-insecure bool
cache.remote.insecure_reason MAGUS_CACHE_REMOTE_INSECURE_REASON --cache-remote-insecure-reason string
cache.remote.trusted_keys MAGUS_CACHE_REMOTE_TRUSTED_KEYS (env only) list (comma-separated, env only)
cache.remote.write.enabled MAGUS_CACHE_REMOTE_WRITE_ENABLED (env only) bool (env only)
cache.size_mb MAGUS_CACHE_SIZE_MB --cache-size-mb int
cache.write.enabled MAGUS_CACHE_WRITE_ENABLED (env only) bool (env only)

ci

Config key Environment variable Flag Type
ci.max_shards MAGUS_CI_MAX_SHARDS --ci-max-shards int
ci.record_runs MAGUS_CI_RECORD_RUNS --ci-record-runs bool
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)

diff

Config key Environment variable Flag Type
diff.tui MAGUS_DIFF_TUI (env only) bool (env only)

general

Config key Environment variable Flag Type
broker MAGUS_BROKER --broker string
concurrency MAGUS_CONCURRENCY -j, --concurrency int
concurrency_profile MAGUS_CONCURRENCY_PROFILE --concurrency-profile string
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
max_failures MAGUS_MAX_FAILURES --max-failures int
stall_timeout MAGUS_STALL_TIMEOUT --stall-timeout duration
target_timeout MAGUS_TARGET_TIMEOUT --target-timeout duration

hints

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

jobs

Config key Environment variable Flag Type
jobs.default_timeout MAGUS_JOBS_DEFAULT_TIMEOUT --jobs-default-timeout duration
jobs.max_depth MAGUS_JOBS_MAX_DEPTH --jobs-max-depth int
jobs.max_live MAGUS_JOBS_MAX_LIVE --jobs-max-live int
jobs.stale_after MAGUS_JOBS_STALE_AFTER --jobs-stale-after duration

knowledge

Config key Environment variable Flag Type
knowledge.duplication.include_tests MAGUS_KNOWLEDGE_DUPLICATION_INCLUDE_TESTS --knowledge-duplication-include-tests bool
knowledge.duplication.min_callees MAGUS_KNOWLEDGE_DUPLICATION_MIN_CALLEES --knowledge-duplication-min-callees int
knowledge.duplication.min_score MAGUS_KNOWLEDGE_DUPLICATION_MIN_SCORE --knowledge-duplication-min-score float
knowledge.duplication.min_shared MAGUS_KNOWLEDGE_DUPLICATION_MIN_SHARED --knowledge-duplication-min-shared int
knowledge.duplication.min_span_ratio MAGUS_KNOWLEDGE_DUPLICATION_MIN_SPAN_RATIO --knowledge-duplication-min-span-ratio float
knowledge.max_size_mb MAGUS_KNOWLEDGE_MAX_SIZE_MB --knowledge-max-size-mb int
knowledge.notes.private MAGUS_KNOWLEDGE_NOTES_PRIVATE --knowledge-notes-private string
knowledge.notes.shared MAGUS_KNOWLEDGE_NOTES_SHARED --knowledge-notes-shared string
knowledge.published_ref MAGUS_KNOWLEDGE_PUBLISHED_REF --knowledge-published-ref string
knowledge.sessions.disabled MAGUS_KNOWLEDGE_SESSIONS_DISABLED --knowledge-sessions-disabled bool
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)
mcp.insecure_bind MAGUS_MCP_INSECURE_BIND --mcp-insecure-bind bool

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.env.passthrough MAGUS_SANDBOX_ENV_PASSTHROUGH (env only) list (comma-separated, env only)
sandbox.mode MAGUS_SANDBOX --sandbox string

secret

Config key Environment variable Flag Type
secret.interactive_timeout MAGUS_SECRET_INTERACTIVE_TIMEOUT --secret-interactive-timeout duration
secret.unattended_timeout MAGUS_SECRET_UNATTENDED_TIMEOUT --secret-unattended-timeout duration

server

Config key Environment variable Flag Type
server.address MAGUS_SERVER_ADDRESS --server-address string
server.enabled MAGUS_SERVER_ENABLED --server-enabled bool
server.idle_ttl MAGUS_SERVER_IDLE_TTL --server-idle-ttl duration
server.maintenance.check_review MAGUS_SERVER_MAINTENANCE_CHECK_REVIEW --server-maintenance-check-review duration
server.maintenance.prune_preserved MAGUS_SERVER_MAINTENANCE_PRUNE_PRESERVED --server-maintenance-prune-preserved duration
server.maintenance.rotate_activities MAGUS_SERVER_MAINTENANCE_ROTATE_ACTIVITIES --server-maintenance-rotate-activities duration
server.maintenance.rotate_logs MAGUS_SERVER_MAINTENANCE_ROTATE_LOGS --server-maintenance-rotate-logs duration
server.maintenance.sync_graph MAGUS_SERVER_MAINTENANCE_SYNC_GRAPH --server-maintenance-sync-graph duration
server.workspaces MAGUS_SERVER_WORKSPACES (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. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. StatusServiceStatusService serves the snapshot, and streams it for a live dashboard.
generatedinternal/config/config.goconfigmagus.yamlconfigurationenvironment variablesflagsreference
Last updated (a9ff8609)
Earlier changes on this page (7)

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.

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.

Broker

The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. See server.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

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.

Span

OpenTelemetry's name for one unit of work under a trace - a target execution, whose sub-operations are child spans. An output reference points at a span's captured output. See telemetry.

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 server.

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 server.

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.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.