Installation

This page gets AGH onto one machine and prepares the local runtime for real work. By the end, you will have a working agh binary, a bootstrapped ~/.agh home, and the prerequisites needed for your first durable session.

Before You Begin

Make sure you have:

• macOS or Linux. AGH currently targets local-first Unix-like environments.
• Release verification tools. The curl installer requires curl, tar, cosign, and either sha256sum or shasum.
• At least one supported agent CLI such as Claude Code, OpenClaw, Hermes, or another ACP-compatible agent runtime you already use.
• Provider credentials available to the daemon. Direct env: refs read API keys from the daemon environment, while vault:providers/<provider>/<slot> refs use encrypted AGH-managed values saved through settings.

Example:

export OPENAI_API_KEY="..."

Install the Binary

Option 1: curl installer

This is the recommended path on macOS and Linux:

curl -fsSL https://agh.network/install.sh | sh

The installer detects your platform, downloads the matching GitHub release archive, verifies checksums.txt with its cosign signature, verifies the archive checksum, installs agh, runs agh version, and opens agh install when an interactive terminal is available.

Use flags when you need a pinned or scripted install:

curl -fsSL https://agh.network/install.sh | sh -s -- --version v0.1.0 --dir "$HOME/.local/bin"
curl -fsSL https://agh.network/install.sh | sh -s -- --skip-bootstrap
curl -fsSL https://agh.network/install.sh | sh -s -- --dry-run

Environment variables are equivalent for automation:

curl -fsSL https://agh.network/install.sh |
  AGH_VERSION=v0.1.0 AGH_INSTALL_DIR="$HOME/.local/bin" AGH_SKIP_BOOTSTRAP=1 sh

If the target directory is not on your PATH, the installer prints the exact directory to add.

Option 2: package manager releases

Tagged releases publish archive checksums, cosign checksum signatures, SBOMs, a Homebrew cask, and Linux .deb and .rpm packages.

brew install --cask pedronauck/agh/agh

For Linux package installs, download the .deb or .rpm for your architecture from the GitHub release, verify it against checksums.txt, then install it with your distribution package manager.

Option 3: build from a repository checkout

Use this when you are already working from the AGH source tree or want a local build artifact you control explicitly. This path requires Go 1.25 or later.

git clone https://github.com/compozy/agh
cd agh
go build -o ./bin/agh ./cmd/agh
export PATH="$PWD/bin:$PATH"

Verify the Install

Confirm that the binary is available:

agh version

If your shell reports command not found, fix PATH first. Do that before you continue.

Bootstrap the AGH Home

The curl installer runs this step automatically when it can access an interactive terminal. If you used --skip-bootstrap, a package manager, or a source build, run the interactive bootstrap once:

agh install

This creates or updates:

• ~/.agh/config.toml
• ~/.agh/agents/general/AGENT.md

The bootstrap flow lets you pick a default provider and model for the built-in general agent.

Manage the Install

Use agh config path to inspect the exact global and workspace config files AGH will read, and use agh config validate after manual edits. agh config show, agh config list, and agh config get <path> always redact environment-backed MCP and config values before printing. Use agh config validate --repair-env --workspace <path> when a workspace .env needs an explicit, bounded repair.

agh update reports whether the binary is managed by a package manager through AGH_MANAGED. When managed, it defers to that package manager; otherwise it points you at the manual release update path. agh uninstall removes runtime launch artifacts idempotently and preserves ~/.agh unless you explicitly pass --purge --force.

Sanity Check the Runtime Inputs

Before moving to Quick Start, verify these three things:

1. agh version succeeds.
2. agh install completed, either from the curl installer or manually, and created ~/.agh/config.toml.
3. agh config validate reports a valid config.
4. Your provider credential is exported in the shell you will use to start the daemon.

Next Step

Continue to Quick Start. That tutorial assumes the binary works, ~/.agh exists, and your provider environment is already available to the daemon.