1.0.-Installing-Harbor.md

Installing Harbor

Harbor lets you run local LLMs and 50+ AI services with simple commands. Get Open WebUI + Ollama running in minutes.

At a Glance

Table of Contents

• Quick Start
• Agent Install Prompt
• Complete Installation Guide
  • Windows
  • macOS
  • Linux
• GPU Acceleration (Optional)
• Harbor CLI Installation Methods
  • Quick Install Script
  • Manual Install
• Harbor App (GUI)
• Troubleshooting

Quick Start

For users who already have Docker and Git installed.

Prerequisites Check

• Docker installed and running (docker --version)
• Docker Compose 2.23.1+ installed (docker compose version)
• Git installed (git --version)
• 10GB+ free disk space

Install Harbor

Choose your preferred method:

Quick Install Script (Recommended)

curl -fsSL https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.sh | bash

Verify Installation

harbor --version
harbor doctor  # Check system compatibility

Start Using Harbor

harbor up    # Start default services (Ollama + Open WebUI)
harbor open  # Open in browser

✓ Done! What's next?

• Harbor User Guide
• Available Services
• CLI Reference

Agent Install Prompt

Use install.md when you want an agentic coding tool to install Harbor for you. The prompt tells the agent to orchestrate the install through Harbor's install.sh (which installs dependencies by default) and verify with harbor --version and harbor doctor.

# With Claude Code
curl -fsSL https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.md | claude

# With Codex
codex "$(curl -fsSL https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.md)"

This is the recommended path for Claude Code, Codex, and similar local agents. Use the quick script directly when you are installing Harbor yourself.

Complete Installation Guide

New to Docker? No problem. Choose your platform below for step-by-step instructions.

Harbor is a containerized toolkit that runs on top of Docker. This enables Harbor to support so many services and work across platforms. The sections below guide you through setting up Docker and all prerequisites.

wsl --install

wsl --version

docker --version
docker compose version
docker run hello-world

sudo apt update && sudo apt install git -y

git --version

docker --version
docker compose version
docker run hello-world

git --version

brew install git

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl start docker
sudo systemctl enable docker

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

docker --version
docker compose version
docker run hello-world

sudo apt-get install git -y

sudo dnf install git -y

git --version

GPU Acceleration (Optional)

Should you set this up?

• ✓ You have an NVIDIA or AMD GPU
• ✓ You want 3-10x faster inference for local LLMs

NVIDIA Setup

Ubuntu/Debian:

# Add NVIDIA Container Toolkit repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Arch Linux:

# Install from official repositories
sudo pacman -S nvidia-container-toolkit

# Configure Docker runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Windows (WSL2): Follow the Ubuntu/Debian instructions above inside your WSL2 terminal.

Verify:

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

You should see your GPU information ✓

AMD Setup (ROCm)

Use this method if you have an AMD Radeon GPU (RX 6000/7000 series or newer recommended).

Ubuntu (22.04 / 24.04):

# 1. Add ROCm GPG key
wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
  gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null

# 2. Add repository
source /etc/os-release
echo "deb [signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amd-container-toolkit/apt/ $VERSION_CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/amd-container-toolkit.list

# 3. Install
sudo apt update && sudo apt install -y amd-container-toolkit

# 4. Configure Docker
sudo amd-ctk runtime configure
sudo systemctl restart docker

Fedora / RHEL:

# 1. Add repository and install
sudo dnf config-manager --add-repo https://repo.radeon.com/amd-container-toolkit/el9/main/amd-container-toolkit.repo
sudo dnf install -y amd-container-toolkit

# 2. Configure Docker
sudo amd-ctk runtime configure
sudo systemctl restart docker

Verify:

docker run --rm --runtime=amd -e AMD_VISIBLE_DEVICES=all ubuntu ls -l /dev/dri

Expected output: /dev/dri/renderD128 shown in the container.

✓ GPU Enabled! Harbor will automatically use GPU for supported services when available.

Harbor CLI Installation Methods

Choose your preferred installation method. All methods work equally well.

Quick Install Script (Recommended)

This automated script:

• Installs system dependencies (Git, curl, Docker, Docker Compose) by default via requirements.sh
• Clones Harbor to ~/.harbor
• Adds Harbor to your PATH
• Works on Linux, macOS, and Windows (WSL2)

curl -fsSL https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.sh | bash

If Docker, Git, and Docker Compose are already installed and you want to skip the dependency step:

curl -fsSL https://raw.githubusercontent.com/av/harbor/refs/heads/main/install.sh | bash -s -- --skip-requirements

On Windows: Run this inside your WSL2 terminal, not PowerShell.

Manual Install

Same as the quick install script, but manual. You can install Harbor to any location:

# Default location
git clone https://github.com/av/harbor.git ~/.harbor
cd ~/.harbor

# Or a custom location
git clone https://github.com/av/harbor.git /path/to/harbor
cd /path/to/harbor

# Make Harbor CLI available globally
./harbor.sh ln

# Verify installation
harbor --version

The harbor update command works the same way regardless of install location.

Troubleshooting:

• If harbor command not found after install, restart your shell
• On some systems, you may need to manually add ~/.local/bin to PATH

Verify Your Installation

After installing via any method:

# Check Harbor version
harbor --version

# Check system compatibility
harbor doctor

# View available commands
harbor --help

Expected output from harbor doctor:

• ✓ Docker installed and running
• ✓ Docker Compose 2.23.1 or newer
• ✓ Git installed
• ✓ Sufficient disk space

✓ Installation Complete!

Next steps:

# Start default services (Ollama + Open WebUI)
harbor up

# Open in browser
harbor open

# Browse available services
harbor ls

Learn more:

• Harbor User Guide - How to use Harbor
• Available Services - Browse 50+ services
• CLI Reference - Complete command reference

Troubleshooting

harbor doctor

The harbor doctor command checks your system for common issues:

harbor doctor

This will verify:

• Docker installation and daemon status
• Docker Compose version compatibility
• Git installation
• Disk space availability
• File permissions
• Bash version

Common Issues

"docker: command not found"

• Docker is not installed or not in PATH
• On Windows: Make sure you're running commands in WSL2, not PowerShell
• Solution: Follow the Complete Installation Guide for your platform

"Cannot connect to the Docker daemon"

• Docker Desktop is not running
• Solution: Start Docker Desktop and wait for it to fully initialize

"docker compose: command not found" or version too old

• Docker Compose plugin not installed or outdated
• Solution: Install/update Docker Compose plugin (minimum version 2.23.1)
• Check version: docker compose version

"Permission denied" when running docker commands

• On Linux: User not in docker group
• Solution: sudo usermod -aG docker $USER then log out and back in
• On Windows/macOS: Docker Desktop permissions issue

Services fail to start with GPU errors (NVIDIA or AMD)

• NVIDIA Container Toolkit not properly installed
• AMD: amd runtime not configured or /dev/kfd missing permission
• Solution: See GPU Acceleration section. For AMD, ensure you ran amd-ctk runtime configure.

"harbor: command not found" after installation

• PATH not updated or shell not restarted
• Solution: Restart your terminal or run source ~/.bashrc (or ~/.zshrc)
• Manual fix: Add ~/.local/bin to your PATH (Harbor links the CLI there via harbor.sh ln)

Services download slowly or fail

• Large Docker images (especially with CUDA)
• Solution: Be patient, first download can take 10-30 minutes depending on your internet
• Retry: harbor down && harbor up

Need more help?

• Join our Discord community
• Check GitHub Issues
• Read the CLI Reference

Harbor App (GUI)

Alternative to the command-line interface.

Harbor App provides a graphical interface for managing Harbor services. It's built on top of the Harbor CLI.

On first launch, the app can install Harbor and host prerequisites for you through a guided setup flow. You only need to download and install the Harbor App package first; the CLI install is optional beforehand.

When to Use Harbor App

Use Harbor App if you:

• Prefer graphical interfaces over command-line
• Want visual service management
• Want App-first install on Linux, macOS, or Windows (WSL2)
• Are comfortable with beta software

Use Harbor CLI if you:

• Comfortable with terminal commands
• Want the most stable experience
• Need all features and latest updates
• Prefer installing Harbor manually before opening the app

Prerequisites

App package only (recommended path)

• Harbor App installed from releases
• Linux, macOS, or Windows 10/11 with WSL2 capability (Windows)
• Administrator or sudo access when the guided installer needs it
• Network access for Docker images and Harbor install scripts

Already have Harbor CLI (optional)

• harbor on PATH (or in WSL for Windows) and harbor doctor passing
• Docker daemon running when you start services

If the CLI is missing, launch the app and use Install Harbor on the setup screen. See Harbor App — Guided setup for platform-specific behavior.

Installation by Platform

# Download the .deb file from releases
sudo dpkg -i Harbor_*.deb

# If dependencies missing:
sudo apt-get install -f

# Download the .AppImage file from releases
chmod +x Harbor_*.AppImage
./Harbor_*.AppImage

sudo xattr -d com.apple.quarantine ./Harbor.app

Next Steps with Harbor App

After installing the app package:

1. Launch the app — Complete guided setup if prompted, or confirm Ready if harbor is already installed
2. Verify the CLI — Open the CLI screen and confirm harbor doctor passes
3. Browse services — See all 50+ available services on the Home screen
4. Start services — Start the default stack or individual services (for example Open WebUI and a backend)
5. Monitor status — View running services and their logs

# Equivalent CLI steps after setup is ready
harbor doctor
harbor up
harbor open

Learn more:

• Harbor App Guide
• Available Services

Additional Resources

System Requirements Summary

Minimum:

• 10GB free disk space (more recommended for multiple services)
• 8GB RAM (16GB+ recommended for LLMs)
• Docker 20.10+
• Docker Compose 2.23.1+
• Bash 3.2+

Recommended:

• 50GB+ free disk space
• 16GB+ RAM
• NVIDIA GPU (optional, for faster inference)
• SSD storage (for better performance)

Bash Version Check

Harbor requires Bash 3.2 or newer (available by default on most systems):

bash --version

If you encounter Bash-related issues, please report them.

Getting Help

• Discord: Join our community server for live support
• GitHub Issues: Report bugs or request features at github.com/av/harbor/issues
• Documentation: Browse the Harbor Wiki
• CLI Reference: See all commands in Harbor CLI Reference

What's Next?

Now that Harbor is installed:

1. Learn the basics: Harbor User Guide
2. Explore services: Browse 50+ services
3. Master the CLI: Complete CLI Reference
4. Join the community: Discord

Popular first services to try:

• Open WebUI - ChatGPT-like interface
• Ollama - Run local LLMs
• ComfyUI - Image generation
• n8n - Workflow automation

Welcome to Harbor! 🚢