Homebrew tap for the Agent Assembly
aasmCLI.
This repository is the official Homebrew tap for installing the aasm
command-line tool — the operator front-end for the
Agent Assembly
governance runtime. The tap's default formula, Formula/aasm.rb, downloads a
pre-built aasm binary from the upstream
GitHub Releases
and installs it onto your PATH. Additional components — runtime, proxy, and
eBPF — are separate formulae (see Components).
Note
Current state — pre-release (release candidate).
The tap tracks pre-release (release-candidate) builds of aasm. Every
formula is pinned to v0.0.1-rc.6 via the shared version source of truth
(metadata/versions.rb), and each sha256 is verified
against the real release artifacts (see Checksum readiness).
The aasm CLI, aasm-runtime, and aasm-proxy all install from published
v0.0.1-rc.6 artifacts today; aasm-bundle and aasm-ebpf are intentionally
disabled until their artifacts ship (see Components).
There is no stable (vX.Y.0) release yet, so installs pull a pre-release
binary. Expect breaking changes until the first stable tag is cut.
brew install ai-agent-assembly/tap/aasmOr tap once, then install by short name:
brew tap ai-agent-assembly/tap
brew install aasmImportant
The canonical tap is ai-agent-assembly/tap — the repository is named
homebrew-tap, and Homebrew strips the homebrew- prefix. aasm installs the
CLI only; it never installs or starts a background runtime. The org id is
lowercase ai-agent-assembly everywhere.
Note
Migrating from the old tap name? Earlier docs used
brew install ai-agent-assembly/agent-assembly/aasm (repo
homebrew-agent-assembly). That command still works — GitHub redirects the
renamed repository — but it is deprecated. Switch to
ai-agent-assembly/tap/aasm. To move an existing checkout:
brew untap ai-agent-assembly/agent-assembly # optional; old tap
brew install ai-agent-assembly/tap/aasmPrefer a tap-less, dependency-free install? The upstream project also ships a
curl | sh one-line installer. See the core repo's
Install the CLI
section for the installer command, the install endpoint, and version pinning.
(That installer endpoint is provisioned alongside the tap bootstrap under
AAASM-1201 and may
not be live yet during the pre-release window.)
aasm installs the CLI only. Every other component is a separate formula, so
you install exactly what you want and nothing starts automatically.
| Formula | Installs | Platforms | Service |
|---|---|---|---|
aasm |
aasm CLI |
macOS · Linux | — |
aasm-runtime |
local runtime daemon | macOS · Linux | brew services (opt-in) |
aasm-proxy |
sidecar proxy enforcement | Linux only | — |
aasm-ebpf |
eBPF kernel enforcement | Linux only | — |
aasm-bundle |
CLI + runtime + proxy (meta) | Linux only | — |
brew install ai-agent-assembly/tap/aasm-runtime
brew install ai-agent-assembly/tap/aasm-proxy
brew install ai-agent-assembly/tap/aasm-ebpf # Linux only
brew install ai-agent-assembly/tap/aasm-bundle # convenience bundleInstalling aasm-runtime does not start it. Manage it explicitly with
Homebrew services:
brew services start aasm-runtime
brew services stop aasm-runtimeNote
aasm-runtime and aasm-proxy install from the component-aware release
artifacts tracked under
AAASM-3951, with
sha256 values verified against the published v0.0.1-rc.6 assets. The
aasm-bundle and aasm-ebpf formulae stay disabled until their artifacts
ship — brew install reports a clear "disabled" message rather than a 404
(bundle: AAASM-4879;
eBPF: AAASM-4325).
| OS | Architecture | Target triple |
|---|---|---|
| macOS | Apple Silicon (M-series) | aarch64-apple-darwin |
| macOS | Intel | x86_64-apple-darwin |
| Linux | ARM64 | aarch64-unknown-linux-gnu |
| Linux | x86_64 | x86_64-unknown-linux-gnu |
The formula selects the correct artifact for your platform using Homebrew's
on_macos / on_linux and on_arm / on_intel blocks. Each artifact is a
pre-built binary published to the upstream
GitHub Releases;
nothing is compiled from source at install time.
aasm --versionThis should print the installed aasm version. From there, common entry points are:
aasm topology # inspect the agent topology
aasm policy # manage policy
aasm dashboard # launch the operator TUIFull CLI documentation lives on the canonical docs site: https://docs.agent-assembly.com/.
brew update
brew upgrade aasmbrew update refreshes this tap; brew upgrade aasm installs the newest
formula version. While the tap tracks pre-releases, each upgrade may pull a new
release-candidate build.
brew uninstall aasm
brew untap ai-agent-assembly/tap # optional — removes the tap itselfbrew uninstall removes the aasm binary. The optional brew untap removes
the tap from your Homebrew installation.
| Symptom | Likely cause and fix |
|---|---|
Error: No available formula with the name "aasm" |
The tap is not added. Run brew tap ai-agent-assembly/tap first, or use the fully-qualified brew install ai-agent-assembly/tap/aasm. |
Error: aasm: ... SHA256 mismatch |
The local formula is stale or the release asset changed. Run brew update, then retry. If it persists, open an issue. |
curl: ... 404 while downloading the bottle |
The pinned release asset is missing or the tag was deleted upstream. Verify the formula's version against the releases page. |
aasm: command not found after install |
brew --prefix/bin is not on your PATH. Add it (e.g. eval "$(brew shellenv)") and restart your shell. |
| Install hangs or fails behind a proxy | GitHub Releases must be reachable. Set HOMEBREW_GITHUB_API_TOKEN and/or your proxy env vars (HTTPS_PROXY) and retry. |
Still stuck? Collect brew config and brew install --verbose aasm output and
file an issue.
- Formula path:
Formula/aasm.rb - Formula version:
0.0.1-rc.6(pre-release / release candidate) - Class:
Aasm(Homebrew maps the fileaasm.rbtoaasm) - License: MIT (matches this tap; the core runtime is Apache-2.0)
- Install: drops the
aasmbinary into Homebrew'sbin - Test:
brew testrunsaasm --versionand asserts the output
The sha256 value for each platform artifact in Formula/aasm.rb is verified
against the SHA256SUMS manifest published with the upstream
v0.0.1-rc.6 release.
All four platform checksums are present and match the published assets, so the
formula is installable today. The aasm-runtime and aasm-proxy formulae carry
the same verified, release-matched checksums for their published v0.0.1-rc.6
artifacts.
| Channel | State |
|---|---|
| Pre-release (release candidate) | Active. Every formula pinned to v0.0.1-rc.6. This is what installs today. |
Stable (vX.Y.0) |
Not yet cut. No stable tag exists. When the first stable release ships, the formulae will be re-pointed to it and this section updated. |
The formula's url and sha256 lines must stay in lock-step with the upstream
agent-assembly releases. The intended flow:
- Upstream
agent-assemblycuts a release and publishes the per-platformaasm-<target>.tar.gzartifacts plus aSHA256SUMSmanifest. - The release-side automation bumps
version, rewrites eachurl, and copies the matchingsha256fromSHA256SUMSintoFormula/aasm.rb, then opens a PR against this tap. - CI (
brew style+brew audit+ a macOS install/test) gates the bump. - On merge,
brew upgrade aasmpicks up the new version.
Note
The automated checksum-sync workflow is still being finished under
AAASM-1201.
Until it lands, formula bumps for new releases are applied manually using the
same procedure. Manual edits should be limited to the version, url, and
sha256 lines — the formula structure itself is stable.
The version field and github.com/ai-agent-assembly/agent-assembly/releases/download/v<X>/…
URL fragments across every formula in this tap are generated from a single
source of truth at metadata/versions.rb. To bump the
tap version:
- Edit
VERSIONinmetadata/versions.rb. - Run
ruby scripts/generate_formulas.rb— this rewrites the bounded# BEGIN GENERATED: version/# END GENERATED: versionblocks in everyFormula/*.rb. - Commit both the SoT change and the regenerated formulae together.
- The CI job
.github/workflows/formula-drift.ymlre-runs the generator on every PR that touchesFormula/**or the SoT and fails if the tree is out of sync. This is what caught theaasm-bundle/aasm-proxy/aasm-ebpfstaying pinned atv0.0.1-rc.2whileaasm.rbmoved tov0.0.1-rc.3— the exact drift class this generator prevents.
Do not hand-edit the version line or url version fragment in any
formula. Do hand-edit sha256 values — those are release-artifact fingerprints
that the release automation resolves and are intentionally outside the
generator's scope.
Contributors and CI run the standard Homebrew checks. To validate locally:
# Lint formula style
brew style ./Formula/
# Strict audit (matches CI)
brew audit --strict --tap ai-agent-assembly/tap
# Install + run the formula's own test block
brew install ai-agent-assembly/tap/aasm
brew test ai-agent-assembly/tap/aasmCI (.github/workflows/tests.yml) runs
brew style and brew audit --strict on every change to Formula/**, plus a
real brew install + brew test on macOS. Link checks: keep all cross-links in
this README pointing at the lowercase ai-agent-assembly org and verify they
resolve before merging.
Note
Organisation GitHub Actions billing is currently suspended, so CI runs may be queued or skipped until billing is restored. Run the validation commands above locally in the meantime.
PRs are welcome — most changes here are formula bumps (usually automated) or
documentation. Please follow the
pull request template and ensure
brew style / brew audit pass locally. Reviews are routed via
CODEOWNERS.
- Core runtime & releases: https://github.com/ai-agent-assembly/agent-assembly · Releases
- Organization profile: https://github.com/ai-agent-assembly
- Documentation site: https://docs.agent-assembly.com/
- Release process:
agent-assemblyreleases and the upstream release workflow - Issues / support: https://github.com/ai-agent-assembly/homebrew-tap/issues
- Security: report vulnerabilities to security@agent-assembly.dev (see the org security policy)
MIT © Agent Assembly contributors