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

MGS2004: sandbox config unresolved

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: "$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 (3269ac7f)
Earlier changes on this page (4)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace in full.

Project

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

Magusfile

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

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. Target in full.

Op

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

Spell

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

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.

Sandbox

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

Trace

OpenTelemetry's name for one whole magus invocation; every target it runs is a span beneath it. Trace in full.

Tool

An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.

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 daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job in full.

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. Run in full.

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. Lease in full.

Conventions

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