magus v0.4.3 is out. See what's new
¶ View generated markdown
2 min read

magus-broker

The per-user process holding this host's capacity and shared services

Synopsis

magus broker [status|stop|units] [flags]

Description

The broker holds this host's capacity: the concurrency slots and declared memory_mb every magus on it shares, and the services runs keep warm between them. Every run asks it before starting a step; a step that does not fit alongside what other invocations hold is refused with MGS3009 (exit 75).

A run starts a broker when none answers, and prints one line saying so. It loads no workspace, records no telemetry and listens on a unix socket only ($XDG_RUNTIME_DIR/magus/broker.sock). It exits once it has held nothing (no claim, no service with a dependent) for ten minutes; a started broker logs to $XDG_STATE_HOME/magus/broker.log.

Each run holds one connection to it for its life, and every claim and service reference rides that connection, so a run killed outright releases what it held at once. When a broker dies with runs still going, they re-assert their claims on the next one.

The broker setting in magus.yaml decides what a run does about it: required refuses a step when none answers (MGS3022, exit 69), best-effort (the default) runs unarbitrated and says so once, off never starts or contacts one.

Run with no target, it serves in this process and logs to stderr. Under systemd it takes the socket the supervisor hands over (LISTEN_FDS), refusing one that is malformed or bound anywhere but broker.sock. `magus broker units` prints the systemd or launchd units for it; magus never installs them.

Options

--idle-exit duration (default: 10m0s)
Exit once the broker has held nothing this long; 0 never exits, for a supervisor that keeps it alive

broker stop options

--services
Stop the broker's hosted services, leaving the broker running

Subcommands

status
The broker: its capacity, every claim holding it, and its services
stop
Stop the broker, or with --services only the services it hosts
units
Print the systemd or launchd units that supervise the broker

Examples

Is a broker up, and what holds capacity

magus broker status

Stop the services it keeps warm

magus broker stop --services

Print the systemd units that socket-activate it

magus broker units systemd

Never start or ask one, for this run

magus run test . --broker off

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(1), magus-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-shell(1), magus-vcs(1), magus-queue(1), magus-doctor(1), magus-config(1), magus-session(1), magus-memory(1), magus-job(1), magus-notes(1), magus-diff(1), magus-server(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-spell(1), magus-agent(1), magus-self(1), magus-version(1)

ManpagePages in this section. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. DoctrineThe standing design decisions: the principles magus is built by, the standard it is measured against, and the line between what it automates and what it leaves to your judgment. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect.
generatedinternal/cli/registry.goclimagus brokerbrokercapacitymemory_mbservicesconcurrency
Last updated (89ab1781)
Earlier changes on this page (1)

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.

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.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

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.

Slot

One unit of the pool's capacity. A target acquires the slots it needs to run (most take one) and releases them when it finishes; the pool tracks capacity (total slots), running (acquired), and queued (blocked). 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.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

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.

Invocation

One magus process's recorded facts - the targets it finished, their outcomes, the lease it acted as, and the session it ran in when a host delivered one - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

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.