peregrine/docs/getting-started/installation.md

Installation

This page walks through a full Peregrine installation from scratch.

---

Prerequisites

• Git — to clone the repository
• Internet connection — install.sh downloads Docker/Podman and other dependencies
• Operating system: Ubuntu/Debian, Fedora/RHEL, Arch Linux, or macOS (with Docker Desktop)

!!! warning "Windows" Windows is not supported. Use WSL2 with Ubuntu instead.

---

Step 1 — Clone the repository

git clone https://git.opensourcesolarpunk.com/Circuit-Forge/peregrine
cd peregrine

---

Step 2 — Run install.sh

bash install.sh

install.sh performs the following automatically:

1. Detects your platform (Ubuntu/Debian, Fedora/RHEL, Arch, macOS)
2. Installs Git if not already present
3. Installs Docker Engine (or Podman if Docker is not available) via official repositories
4. Adds your user to the docker group so you do not need sudo for docker commands (Linux only — log out and back in after this)
5. Detects NVIDIA GPUs — if nvidia-smi is present and working, installs the NVIDIA Container Toolkit and configures Docker/Podman to use it
6. Creates .env from .env.example — edit .env to customise ports and model storage paths before starting

!!! note "macOS" install.sh installs Docker Desktop via Homebrew (brew install --cask docker) then exits. Open Docker Desktop, start it, then re-run the script. Ollama can also run natively for Metal GPU-accelerated inference — see the macOS note in Step 4.

!!! note "GPU requirement" For GPU support, nvidia-smi must return output before you run install.sh. Install your NVIDIA driver first.

---

Step 2a — Podman users: GPU CDI setup

If you prefer rootless Podman over Docker, install.sh detects it and manages.sh/make use it automatically. For GPU profiles to work with Podman you must generate a CDI spec first:

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

This needs to be done once after driver installation. Without it, GPU profiles will start but containers will not have GPU access. Docker users can skip this step — Docker uses --gpus all instead of CDI.

---

Step 3 — (Optional) Edit .env

The .env file controls ports and volume mount paths. The defaults work for most single-user installs:

# Main UI port
VUE_PORT=8506

# Model paths — use full absolute paths, not ~ (tilde does not expand inside containers)
DOCS_DIR=/home/yourname/Documents/JobSearch
OLLAMA_MODELS_DIR=/home/yourname/models/ollama

# Inference model defaults
OLLAMA_DEFAULT_MODEL=llama3.2:3b

# External API keys — only needed for the "remote" profile or BYOK unlock
ANTHROPIC_API_KEY=

Change VUE_PORT if 8506 is taken on your machine. See Docker Profiles for a full port reference.

---

Step 4 — Start Peregrine

Choose a profile based on your hardware:

./manage.sh start                        # cpu — local Ollama on CPU (recommended default)
./manage.sh start --profile single-gpu   # one NVIDIA GPU
./manage.sh start --profile dual-gpu     # two NVIDIA GPUs
./manage.sh start --profile remote       # no local LLM — use cloud API keys only

manage.sh start runs preflight.py first, which checks for port conflicts and writes GPU/RAM recommendations to .env. Then it calls docker compose (or podman compose) with the right compose file overlay for your hardware.

!!! tip "macOS with native Ollama" If you installed Ollama natively via Homebrew for Metal GPU inference, start with --profile cpu. The container API on port 8506 connects to your host's Ollama at localhost:11434 automatically.

---

Step 5 — Open the UI

Navigate to http://localhost:8506 (or whatever VUE_PORT you set).

The first-run wizard launches automatically. See First-Run Wizard for a step-by-step guide.

---

Supported Platforms

Platform	Tested	Notes
Ubuntu 22.04 / 24.04	Yes	Primary target
Debian 12	Yes
Fedora 39/40	Yes
RHEL / Rocky / AlmaLinux	Yes
Arch Linux / Manjaro	Yes
macOS (Apple Silicon)	Yes	Docker Desktop required; GPU via native Ollama (Metal)
macOS (Intel)	Yes	Docker Desktop required; no GPU support
Windows	No	Use WSL2 with Ubuntu

---

GPU Support

Only NVIDIA GPUs are supported. AMD ROCm is not currently supported.

Requirements:

• NVIDIA driver installed and nvidia-smi working before running install.sh
• CUDA 12.x recommended (CUDA 11.x may work but is untested)
• Minimum 8 GB VRAM for single-gpu profile with default models
• Podman users: CDI spec required — see Step 2a above

For dual-gpu, both cards must be NVIDIA. GPU 0 handles Ollama (cover letters, general tasks) and GPU 1 handles the research workload. The exact behaviour is controlled by DUAL_GPU_MODE — see Docker Profiles.

If your GPU has less than 10 GB VRAM, preflight.py calculates a CPU_OFFLOAD_GB value and writes it to .env. The vLLM container picks this up via --cpu-offload-gb to overflow KV cache to system RAM.

---

Stopping Peregrine

./manage.sh stop       # stop all containers
./manage.sh restart    # stop then start again (runs preflight first)

---

Reinstalling / Clean State

./manage.sh clean      # removes containers, images, and data volumes (destructive)

You will be prompted to type yes to confirm.