Install Runtime¶

Goal: install the runtime binary and confirm it runs.

Engineering Runtime is a single binary. It carries its own authoring specs, command cheatsheets and agent contract inside it, so a fresh machine needs nothing else — no Go toolchain, no source checkout, no cloud CLI. It does not seed a capability library into Runtime Home.

Requirements¶


OS	macOS, Linux or Windows
Arch	`amd64` or `arm64`
Runtime deps	None. The binary is statically linked (`CGO_ENABLED=0`)
Optional	`gh`, `git`, `kubectl`, `terraform`, … — only for the Command Engine binaries you actually use

Available artifacts¶

Releases are published to engineeringruntime/engineering-runtime-releases. Every release ships six archives plus a SHA256SUMS.txt:

Platform	Arch	Archive
macOS	Apple Silicon	`engineering-runtime-<version>-darwin-arm64.tar.gz`
macOS	Intel	`engineering-runtime-<version>-darwin-amd64.tar.gz`
Linux	x86_64	`engineering-runtime-<version>-linux-amd64.tar.gz`
Linux	arm64	`engineering-runtime-<version>-linux-arm64.tar.gz`
Windows	x86_64	`engineering-runtime-<version>-windows-amd64.zip`
Windows	arm64	`engineering-runtime-<version>-windows-arm64.zip`

Each archive contains the runtime binary plus README.md. It also carries reference copies of commands/, configs/ and version-exact schemas/ — those are for browsing only. Nothing reads them at install time. During Bootstrap, the binary refreshes its embedded release-owned contracts; it does not copy the archive's config reference into Runtime Home.

Install with Homebrew (macOS or Linux)¶

Use Homebrew on an interactive macOS or Linux developer machine when Homebrew is already installed:

brew install engineeringruntime/tap/engineering-runtime
"$(brew --prefix)/bin/runtime" version

The fully qualified package name adds the public tap automatically. The formula downloads the same release archive and verifies the same published SHA256 used by the installer below. It supports Apple Silicon, Intel macOS, Linux arm64 and Linux amd64.

If another `runtime` wins on PATH¶

A previous script or manual installation can coexist with Homebrew:

Path	Typical owner
`~/.local/bin/runtime`	Earlier non-root `install.sh` or manual install
`/usr/local/bin/runtime`	Earlier system-wide `install.sh` or manual install
`$(brew --prefix)/bin/runtime`	Current Homebrew formula

Diagnose both the selected binary and the Homebrew-managed binary:

command -v runtime
runtime version
"$(brew --prefix)/bin/runtime" version

If the prefix-qualified command reports the current version but runtime version reports an older one, an existing manual install is earlier on PATH. Prefer Homebrew for the current shell without deleting anything:

export PATH="$(brew --prefix)/bin:$PATH"
hash -r
test "$(command -v runtime)" = "$(brew --prefix)/bin/runtime"
runtime version

For future shells, place the same export PATH=... after other PATH assignments in your shell startup file, then open a new terminal. Inspect the file first—do not blindly append duplicate PATH lines. Alternatively, remove an older manual binary only after confirming its exact path. Do not delete ~/.engineering-runtime; every installation method uses the same Runtime Home.

Install with the verification script¶

No GitHub account or token is required. The release artifacts are public, so a plain curl works. Use this route for CI, containers, machines without Homebrew, or when you want to choose INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/engineeringruntime/engineering-runtime-releases/main/install.sh | sh
runtime version

The installer detects your OS and architecture, verifies the published SHA256 before extracting, installs to /usr/local/bin (or ~/.local/bin when that is not writable), and tells you which it chose.

Variable	Effect
`VERSION=v<tag>`	Install a specific published tag instead of the latest
`INSTALL_DIR=/path`	Install somewhere else

Exit codes — for scripted and AI-driven installs

Distinct on purpose, so a caller can tell these apart:

Code	Meaning
`0`	Success
`1`	Usage or unexpected internal error
`2`	Unsupported platform (OS or architecture)
`3`	Required tool missing (`curl`, `tar`, `shasum`/`sha256sum`)
`4`	Download failed
`5`	Checksum verification failed — nothing is installed
`6`	No writable install directory

Expected output:

Engineering Runtime v<tag> (darwin/arm64)
  downloading engineering-runtime-v<tag>-darwin-arm64.tar.gz
  downloading SHA256SUMS.txt
  verifying checksum

Installed runtime <version>
  location: /usr/local/bin/runtime

Next:
  runtime bootstrap        # prepare the Runtime Home
  runtime config validate  # confirm the install

Then continue to Quick start.

Prefer not to pipe to a shell?

Some environments forbid curl | sh. The manual download-verify-extract path below is a first-class alternative and produces the same result.

Install manually¶

Verify with --ignore-missing

SHA256SUMS.txt covers all six archives in the release. Without --ignore-missing, shasum -c reports the five archives you did not download as failures — which reads like a tampered artifact when nothing is wrong.

Each archive expands to a versioned directory (engineering-runtime-<version>-<os>-<arch>/) containing the runtime binary — not a bare ./runtime.

Install latest by default

The commands below install the latest published release. Pin a tag only when you need a reproducible pipeline — see CI/CD and Migration.

macOSLinuxWindows (PowerShell)CI (GitHub Actions)

# Latest published tag (pin e.g. VERSION=v0.9.1 for reproducible installs)
VERSION=$(curl -fsSL https://api.github.com/repos/engineeringruntime/engineering-runtime-releases/releases/latest \
  | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
ARCH=$([ "$(uname -m)" = "arm64" ] && echo arm64 || echo amd64)
ARCHIVE=engineering-runtime-$VERSION-darwin-$ARCH.tar.gz
BASE=https://github.com/engineeringruntime/engineering-runtime-releases/releases/download/$VERSION

cd ~/Downloads
curl -fsSL -O "$BASE/$ARCHIVE"
curl -fsSL -O "$BASE/SHA256SUMS.txt"

# Verify the download before trusting it
shasum -a 256 -c SHA256SUMS.txt --ignore-missing

tar -xzf "$ARCHIVE"
sudo mv engineering-runtime-$VERSION-darwin-$ARCH/runtime /usr/local/bin/runtime
sudo chmod +x /usr/local/bin/runtime

# macOS quarantines downloaded binaries — clear it, or the OS refuses to run it
sudo xattr -d com.apple.quarantine /usr/local/bin/runtime 2>/dev/null || true

runtime version

No sudo? Install into your home directory instead:

mkdir -p ~/.local/bin
mv engineering-runtime-$VERSION-darwin-$ARCH/runtime ~/.local/bin/runtime
chmod +x ~/.local/bin/runtime
xattr -d com.apple.quarantine ~/.local/bin/runtime 2>/dev/null || true
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

VERSION=$(curl -fsSL https://api.github.com/repos/engineeringruntime/engineering-runtime-releases/releases/latest \
  | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
ARCH=$([ "$(uname -m)" = "aarch64" ] && echo arm64 || echo amd64)
ARCHIVE=engineering-runtime-$VERSION-linux-$ARCH.tar.gz
BASE=https://github.com/engineeringruntime/engineering-runtime-releases/releases/download/$VERSION

cd ~/Downloads
curl -fsSL -O "$BASE/$ARCHIVE"
curl -fsSL -O "$BASE/SHA256SUMS.txt"

sha256sum -c SHA256SUMS.txt --ignore-missing

tar -xzf "$ARCHIVE"
sudo install -m 0755 engineering-runtime-$VERSION-linux-$ARCH/runtime /usr/local/bin/runtime

runtime version

$Version = (Invoke-RestMethod https://api.github.com/repos/engineeringruntime/engineering-runtime-releases/releases/latest).tag_name
$Arch    = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "amd64" }
$Archive = "engineering-runtime-$Version-windows-$Arch.zip"
$Base    = "https://github.com/engineeringruntime/engineering-runtime-releases/releases/download/$Version"

cd ~\Downloads
Invoke-WebRequest "$Base/$Archive" -OutFile $Archive
Invoke-WebRequest "$Base/SHA256SUMS.txt" -OutFile SHA256SUMS.txt

# Verify — compare against the matching line in SHA256SUMS.txt
Get-FileHash $Archive -Algorithm SHA256
Select-String -Path SHA256SUMS.txt -Pattern $Archive

Expand-Archive $Archive -DestinationPath . -Force
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\engineering-runtime" | Out-Null
Copy-Item "engineering-runtime-$Version-windows-$Arch\runtime.exe" `
          "$env:LOCALAPPDATA\Programs\engineering-runtime\runtime.exe" -Force

# Add to PATH permanently — restart the terminal afterwards
setx PATH "$env:PATH;$env:LOCALAPPDATA\Programs\engineering-runtime"

runtime version

Windows SmartScreen may warn on first run because the binary is unsigned. Choose More info → Run anyway, or unblock it first:

Unblock-File $env:LOCALAPPDATA\Programs\engineering-runtime\runtime.exe

Use the shared composite action from engineering-runtime-ci, which downloads, checksum-verifies and bootstraps in one step. Omit version (or pass an empty string) to install latest:

- uses: engineeringruntime/engineering-runtime-ci/.github/actions/setup-runtime@main
  with:
    runtime_github_token: ${{ secrets.RUNTIME_GITHUB_TOKEN }}
    github_organization: my-org      # optional — exported for explicit inputs
    # version:                       # omit or "" = latest release

See CI/CD for pinning a specific tag in production pipelines.

Always verify the checksum

The verification step is not optional ceremony. SHA256SUMS.txt is published alongside every archive precisely so that a truncated download or a tampered artifact fails loudly instead of silently installing.

Verify the install¶

runtime version
runtime bootstrap
runtime config validate

runtime config validate is the single best "is my machine set up correctly" check. It reports where your config, policy, context and capabilities live, which auth providers are enabled and whether they actually authenticate, which allowed binaries are installed, and any policy rule that can never match. It modifies nothing.

Uninstall¶

Remove the binary. Keep the Runtime Home unless you deliberately want to delete your configuration, policy, capabilities and audit history:

HomebrewManual macOS / LinuxWindows (PowerShell)

brew uninstall engineering-runtime

Homebrew removes only its managed binary. It leaves ~/.engineering-runtime intact.

sudo rm -f /usr/local/bin/runtime      # or ~/.local/bin/runtime
rm -rf ~/.engineering-runtime          # deletes your config, policy and audit log

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\engineering-runtime"
Remove-Item -Recurse -Force "$env:USERPROFILE\.engineering-runtime"

Removing the Runtime Home discards its audit log, cache, release-owned local contracts, and any legacy files that still remain there. Config, policy, and capability definitions selected from external sources are not removed. Back up the Home first if its audit history or legacy recovery copies matter.

Next¶

Quick Start — the minimal auth-free local path
Runtime Home — what Bootstrap created and who owns it
Upgrading — what changes and what survives

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.