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

Install on Windows

Warning

Nothing has run these binaries end to end. Both Windows targets are built by the release pipeline and never executed by it: windows/amd64 compiles and links natively, windows/arm64 is cross-compiled and is the newest, least proven target of all. windows/amd64 has shipped for several releases and has field use behind it; windows/arm64 has none.

The Buzz JIT is also newly enabled on Windows and its machine-code path has never run on a Windows machine here. If a magusfile gives a result that looks wrong, set BUZZ_JIT=0 and re-run: if the answer changes, that is a JIT bug to report.

See platform support for the full matrix.

magus ships as a single self-contained binary. Download it with curl.exe, extract it into a PATH directory you own, then verify it before first run. Run these in PowerShell:

Quick install

# The hosted docs substitute the latest release tag below; on GitHub it reads
# literally - get the real value from https://github.com/egladman/magus/releases
$VERSION = "v0.4.3"
$ARCH = "amd64"       # or arm64 on Windows on ARM
curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/magus_${VERSION}_windows_${ARCH}_static.tar.gz"
mkdir -Force $Env:USERPROFILE\bin | Out-Null
tar -xzf "magus_${VERSION}_windows_${ARCH}_static.tar.gz" magus.exe
Move-Item -Force magus.exe $Env:USERPROFILE\bin\magus.exe
magus version

The archive also carries LICENSE, THIRD-PARTY-NOTICES, README.md, and a BUILDINFO file naming the exact version, commit, platform, and variant. Naming magus.exe on the tar line above extracts just the binary; drop it to unpack all of them. BUILDINFO is readable without running anything, which is the point if a dynamically linked build does not start.

Both curl.exe and tar ship with Windows 10 (1803+) and Windows 11, so no extra tooling is needed. $VERSION above is the current release; GitHub Releases lists every build.

To fill in $ARCH from the machine rather than by hand, $Env:PROCESSOR_ARCHITECTURE reads AMD64 or ARM64:

$ARCH = if ($Env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }

Testing status

Windows binaries are built by the release pipeline but are not executed by CI, which runs on Linux only. windows/amd64 has shipped for several releases and has field use behind it; windows/arm64 is new and has never been run end to end.

The Buzz JIT is also newly enabled on Windows (it was disabled there until this release line) and its generated machine code has not executed on any Windows machine during development. If a magusfile gives a result that looks wrong, re-run with the JIT off:

$Env:BUZZ_JIT = "0"
magus run <target>

If the answer changes, that is a JIT bug rather than a magusfile bug, and it is a useful thing to report. See Platform support.

Which archive

The _static archive above is what both architectures ship, and it is what magus self update fetches. No dynamically linked archive is published: on Windows it would link the MSYS2 mingw copies of libzstd/liblzma, which a user's machine has no reason to carry. magus run release-build:dynamic produces one from source if you want it.

Verify the download

Fetch the manifest and its signature next to the tarball:

curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/SHA256SUMS"
curl.exe -fLO "https://github.com/egladman/magus/releases/download/$VERSION/SHA256SUMS.sig"

Then verify the Ed25519 signature first, and only then the checksum: checking a hash against an unverified manifest proves nothing. The exact commands are in Verify a release.

Put it on your PATH

If magus version is not found, add the install directory to your user PATH (persists across sessions):

[Environment]::SetEnvironmentVariable("Path", "$Env:USERPROFILE\bin;$Env:Path", "User")

Open a new PowerShell window afterward, then re-run magus version.

Next steps

SetupInstall magus from a signed release, verify it, set up your shell, and keep it current with magus self update. Knowledge graphThe knowledge graph is a deterministic, cache-backed graph of the magus domain (projects, targets, spells, ops, charms, modules, diagnostics, docs, and buzz sources) that agents and humans query instead of grepping. This page covers the schema, the verbs, the file layout, and how to point external graph tools at an export. ChangelogEvery change to magus, newest first, in Keep a Changelog format, starting with the unreleased entries. Generated from changes/unreleased/ and releases/*.yaml. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files every checkout of the repository shares.
downloadinstallwindowspowershellpath
Last updated (971497a6)
Earlier changes on this page (1)

Full history ↗ · Blame source ↗

Glossary

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.

Manifest

The file that declares what a package is: its name, dependencies, entry points and tool config (go.mod, package.json, pyproject.toml, Cargo.toml). How the workspace builds, tests and lints the package belongs in the magusfile, not in the manifest's scripts. Manifest in full.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. Ward in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI 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.

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

Window

The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session. Window 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

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.