Skip to content

installation.md

Latest commit

 

History

History
211 lines (147 loc) · 6.18 KB

installation.md

File metadata and controls

211 lines (147 loc) · 6.18 KB
Raw

Installation Guide

This guide describes how to install the AI Cluster Runtime (AICR) CLI tool (aicr) on Linux, macOS, or Windows.

What is AICR: AICR generates validated configurations for GPU-accelerated Kubernetes deployments. See README for project overview.

Prerequisites

  • Operating System: Linux, macOS, or Windows (via WSL)
  • Kubernetes Cluster (optional): For agent deployment or bundle generation testing
  • GPU Hardware (optional): NVIDIA GPUs for full system snapshot capabilities
  • kubectl (optional): For Kubernetes agent deployment

Install aicr CLI

Option 1: Homebrew (macOS/Linux)

brew tap NVIDIA/aicr
brew install aicr

Option 2: Automated Installation

Install the latest version using the install script:

curl -sfL https://get.aicr.run | bash -s --

To install to a custom directory instead of the default /usr/local/bin:

curl -sfL https://get.aicr.run | bash -s -- -d ~/bin

Optional: if you hit GitHub API rate limits, set GITHUB_TOKEN before running the install command. No special repository scope is required for public releases.

This script:

  • Detects your OS and architecture automatically
  • Downloads the appropriate binary from GitHub releases
  • Installs to /usr/local/bin/aicr by default (use -d <dir> for a custom location)
  • Installs shell completions for bash, zsh, and fish (set AICR_NO_COMPLETIONS=1 to skip)
  • Verifies the installation
  • Uses GITHUB_TOKEN environment variable for authenticated API calls (avoids rate limits)

Supply Chain Security: AICR includes SLSA Build Level 3 image provenance with signed image SBOMs and verifiable attestations. See SECURITY for verification instructions.

Option 3: Manual Installation

  1. Download the latest release

Visit the releases page and download the appropriate binary for your platform:

  • macOS ARM64 (M1/M2/M3): aicr_<version>_darwin_arm64.tar.gz
  • macOS Intel: aicr_<version>_darwin_amd64.tar.gz
  • Linux ARM64: aicr_<version>_linux_arm64.tar.gz
  • Linux x86_64: aicr_<version>_linux_amd64.tar.gz
  1. Extract and install
# Example for Linux x86_64 (substitute the version you downloaded for 0.15.0)
tar -xzf aicr_0.15.0_linux_amd64.tar.gz
sudo mv aicr /usr/local/bin/
# keep the binary attestation beside it so `aicr bundle --attest` works
[ -f aicr-attestation.sigstore.json ] && sudo mv aicr-attestation.sigstore.json /usr/local/bin/
sudo chmod +x /usr/local/bin/aicr

Option 4: Build from Source

Requirements:

  • Go 1.26 or higher
go install github.com/NVIDIA/aicr/cmd/aicr@latest

Verify Installation

Check that aicr is correctly installed:

# Check version
aicr --version

# View available commands
aicr --help

# Test snapshot (requires GPU)
aicr snapshot --format json | jq '.measurements | length'

Expected output shows version information and available commands.

Post-Installation

Shell Completion

Tab completion for commands and flags is installed automatically by both the Homebrew formula and the install script. No manual setup is required.

Opt out (install script only): set AICR_NO_COMPLETIONS=1 before running the script:

AICR_NO_COMPLETIONS=1 curl -sfL https://get.aicr.run | bash -s --

Manual setup (build from source or go install):

Bash:

aicr completion bash > "${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions/aicr"

Zsh:

aicr completion zsh > "${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions/_aicr"

Fish:

aicr completion fish > ~/.config/fish/completions/aicr.fish

Alternatively, source completions dynamically in your shell RC file (evaluates on every shell start):

# Bash (~/.bashrc)
source <(aicr completion bash)

# Zsh (~/.zshrc)
source <(aicr completion zsh)

Container Images

AICR is also available as container images for integration into automated pipelines:

CLI Image

docker pull ghcr.io/nvidia/aicr:latest
docker run ghcr.io/nvidia/aicr:latest --version

API Server Image (Self-hosting)

docker pull ghcr.io/nvidia/aicrd:latest
docker run -p 8080:8080 ghcr.io/nvidia/aicrd:latest

Next Steps

See CLI Reference for command usage

Troubleshooting

Command Not Found

If aicr is not found after installation:

# Check if binary is in PATH
echo $PATH | grep -q /usr/local/bin && echo "OK" || echo "Add /usr/local/bin to PATH"

# Add to PATH (bash)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission Denied

# Make binary executable
sudo chmod +x /usr/local/bin/aicr

GPU Detection Issues

Snapshot GPU detection is driver-free: it enumerates PCI devices via sysfs (NFD) and resolves the accelerator SKU from the device ID — no nvidia-smi or NVIDIA driver required. The GPU Operator's nvidia.com/gpu.product node label is not required to collect GPU data; when present (read in-cluster via the node topology), it improves SKU accuracy and powers the "GPU placement mismatch" warning. If a snapshot reports no GPU on a node you expect to have one, confirm the agent landed on the GPU node (it needs host /sys access).

Uninstall

# Remove binary
sudo rm /usr/local/bin/aicr

# Remove shell completions (remove whichever exist)
sudo rm -f /usr/share/bash-completion/completions/aicr
sudo rm -f /usr/local/share/zsh/site-functions/_aicr
sudo rm -f /opt/homebrew/share/zsh/site-functions/_aicr
sudo rm -f /opt/homebrew/etc/bash_completion.d/aicr
sudo rm -f /usr/local/etc/bash_completion.d/aicr
rm -f "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/aicr"
rm -f "${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions/_aicr"
rm -f "${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions/aicr.fish"

Getting Help