Skip to content

installation.md

Latest commit

 

History

History
216 lines (148 loc) · 5.75 KB

installation.md

File metadata and controls

216 lines (148 loc) · 5.75 KB

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 installation script:

curl -sfL https://raw.githubusercontent.com/NVIDIA/aicr/main/install | bash -s --

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

curl -sfL https://raw.githubusercontent.com/NVIDIA/aicr/main/install | 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 compliance with signed 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
tar -xzf aicr_linux_amd64.tar.gz
sudo mv aicr /usr/local/bin/
sudo chmod +x /usr/local/bin/aicr
  1. Verify installation
aicr --version

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://raw.githubusercontent.com/NVIDIA/aicr/main/install | 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 measurements require nvidia-smi in PATH:

# Verify NVIDIA drivers
nvidia-smi

# If missing, install NVIDIA drivers for your platform

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