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

MGS2004: sandbox config failed to resolve

A sandbox declaration could not be turned into rules: a sandbox.allow entry or a sandbox.env.passthrough pattern in magus.yaml, a spell's mgs_getSandbox(), or a target's sandbox policy. magus stops before running anything: the workspace's when the policy is built, a spell's when the spell loads, a target's when its magusfile loads.

[MGS2004] sandbox config for /home/user/project: sandbox: "$NONEXISTENT_VAR/cache": variable is unset or empty: NONEXISTENT_VAR
[MGS2004] spell "tool": mgs_getSandbox: allow[0]: path "../cache" must be a relative path that stays under base userCache

Why

A literal sandbox.allow path in magus.yaml supports ~ for the home directory and $VAR references resolved against the current environment. An unset or empty variable expands to nothing, and $UNSET/ would then grant /. A mode outside ro, rw, rx and rwx (a typo such as RW) would grant something other than what was written. A base magus does not know, a path that leaves its base, or a base with no path under it (all of ~/.cache) grants something nobody meant. A passthrough pattern such as GO* matches more than it names (GOOGLE_APPLICATION_CREDENTIALS). Each of these is refused rather than skipped: a sandbox that silently grants less breaks builds nobody can trace, and one that grants more is not a sandbox.

A spell and a target may not write $VAR into a path: a variable unset on one host would fail every run there. They name it in env, or use a $VAR base, which grants nothing while the variable is unset.

Every bad entry is reported at once.

Resolution

  • Check that any $VAR referenced in a magus.yaml path is set, and not empty, in the environment magus runs in, or replace it with an absolute path or an env and base.
  • Use ro, rw, rx or rwx for mode. Exec is never implied, so a directory of tools needs rx.
  • Use a base from the sandbox model, with a relative path under it.
  • Write a passthrough prefix as at least three characters ending in _ (MISE_*, LC_*), or list the variables by name.
  • Remove the entry if it was a typo.

Also fires

When the job store cannot be read while narrowing the sandbox to a lease, magus logs this code as a warning and keeps the workspace's write grant, matching the guard: a lease that stops resolving must not brick the checkout a person is working in.

sandbox diagnosticsLanding page for the sandbox that confines magus spells to the workspace, plus its MGS2xxx diagnostics for denied reads, writes, execs, and env leaks. Sandbox modelThe threat model and allowlist semantics that magus enforces around spell execution, and how the MGS2xxx diagnostics map onto that model. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect.
MGS2004sandboxconfigurationallowlistpath resolutionmagus.yamlspell
Last updated (63e73856)
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.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

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.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

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

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.

Trace

OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. See telemetry.

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.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

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