Install Aegis

These docs do not publish a generic installer URL.

No customer-supported signed macOS package is published today. Dogfood prerelease .pkg assets are not a customer install path. The package details below describe that prerelease artifact for dogfood verification; they do not provide a customer install path.

What the reference package contract proves

The package contract describes a local package operation. It proves that a signed package passed local verification and that the installed aegis command runs on the host. It does not prove account sign-in, GitHub App access, repo onboarding, deploy authority, or app access.

Question	Command
Is the CLI package installed and runnable?	aegis version --json
Is this machine signed in and ready for Forge work?	aegis doctor --json
Can Forge read a specific repo through the GitHub App?	aegis github status --project-repo <owner/repo> --require --json

Reference requirements

• Apple Silicon macOS.
• OpenAI Codex CLI (codex) on PATH.
• Lima with limactl on PATH.
• curl, shasum, pkgutil, spctl, xcrun, and python3 on the host.
• sudo permission to run the Apple package installer.
• Network access to get.mithran.cloud.

The installer itself does not require Docker.

Before you run it

Security teams that review shell installers should inspect the provided script before piping it to sh.

The installer must not require GitHub access or Mithran sign-in before package verification. Sign-in is a separate step: aegis setup.

Verification before sudo

The installer creates a temporary working directory, downloads the package and SHA256SUMS, and verifies the package before installation.

Check	Tool	Failure behavior
Package digest	shasum -a 256 -c	Installation stops before sudo installer.
Developer ID installer signature	pkgutil --check-signature	Installation stops before sudo installer.
Gatekeeper install assessment	spctl --assess --type install	Installation stops before sudo installer.
Notarization ticket	xcrun stapler validate	Installation stops before sudo installer.

If any verification step fails, installation stops before the package installer runs.

After verification, the installer runs:

sudo installer -pkg <downloaded-package> -target /

After the package install completes, the installer runs the installed aegis command with --help as a smoke check.

What is installed

The package installs /Applications/Aegis.app, the aegis product CLI, and host-native public shims under /usr/local/bin.

For Forge work, the commands you use directly are:

• aegis
• map

Use aegis for local setup, sign-in, doctor checks, and GitHub connection evidence. Use map for Forge onboarding, deploy, status, evidence, access, versions, publish, and canary operations.

The app bundle also contains packaged helper and worker components under:

/Applications/Aegis.app/Contents/Library/AegisComponents/

Some helper commands may also have host shims when the packaged component is host-native. Do not depend on undocumented helper commands being present on PATH; use the documented aegis and map commands for setup, deploy, and diagnostics.

The package refuses to install on a Mac that is not arm64-capable.

The package also refuses to overwrite an existing /usr/local/bin/aegis unless that path is already owned by the com.mithran.aegis package receipt or is an Aegis-owned symlink into Aegis.app.

Local command boundary

During package installation, the postinstall script registers the local ABKD command-boundary daemon for the console user when a console user is available. This is a local LaunchAgent registration. It does not sign the user in, contact Mithran services, or grant repository access.

The LaunchAgent is:

~/Library/LaunchAgents/ai.mithran.aegis-secret.abkd.plist

The daemon executable is loaded from inside the signed app bundle:

/Applications/Aegis.app/Contents/Library/AegisComponents/bin/abkd

The daemon socket and logs are under:

~/Library/Application Support/AegisSecret/abkd/

If no console user is available during install, the postinstall step does not fail the package installation.

Verify install

When installation finishes, verify the CLI on your path:

aegis version --json

This proves that the package installed and that the aegis CLI on PATH runs. It does not prove Mithran sign-in, account access, GitHub App installation, or a repo grant.

Read these fields in the JSON output:

Field	Meaning
schema_version	aegis.version.v0.
version	Aegis CLI version installed on PATH.
implementation	CLI implementation. The packaged CLI reports rust.
component_manifest	Present when the packaged component manifest is readable. Use it as component inventory evidence when an IT review asks for packaged binaries or resources.

For an IT change ticket, keep these items with the install record:

• the install command used;
• the package URL, version, and SHA-256 digest shown by the installer or package feed;
• the matching package line from the checksum file when available;
• confirmation that the installer reached the installed aegis --help smoke check;
• the successful aegis version --json output.

After local install verification, continue with Sign in.

If installation stops

The installer stops without installing when the package feed is paused, required tools are missing, the checksum does not match, Apple package verification fails, notarization validation fails, the Mac is not arm64-capable, or an existing /usr/local/bin/aegis cannot be confirmed as Aegis-owned. It also stops if the installed aegis command does not run after installation.

Retry only after the failed condition is corrected. If the failure depends on the Mithran package feed or package verification, use Support and escalation.

What install does not do

• It does not sign you into Mithran.
• It does not install or configure the GitHub App.
• It does not change any repository.
• It does not deploy an app.
• It does not grant Aegis access to source code.

Those steps start with aegis setup.

Next

Sign in.