/run-llms

Run LLMs locally with Harbor

Harbor is a containerized LLM toolkit. Default harbor up starts Open WebUI (webui) and llama.cpp (llamacpp). This skill is the operational playbook for installing Harbor, choosing a backend, pulling models, wiring search/voice/code tools, and pointing coding agents at the same stack.

For the full CLI catalog, harbor skills get harbor. For Boost module authoring, use the boost-modules skill.

Agent rules

• harbor logs follows forever and will hang a non-interactive shell. Read logs with docker logs harbor.<service> (add --tail 200 if needed).
• Never edit .env by hand. Use harbor config get/set and harbor env.
• Do not set llamacpp.model / llamacpp.model.specifier unless the user explicitly wants a single pinned GGUF. Router mode (empty specifier) discovers pulled GGUFs automatically.
• harbor launch options (--backend, --model, --web, --workflow, --config, --service) go before the tool name. Everything after the tool name is the tool's own argv.
• After harbor update, run harbor config update if new keys are missing from the local config.

Read only what you need

Decision trees

User wants to run an LLM

1. Harbor installed? (`harbor --version`)
   → NO: install (see Initial setup)
2. Docker running? (`docker info`)
   → FAIL: start Docker
3. Platform / backend:
   → Apple Silicon Metal: dmr, mlx, or omlx (see backends.md)
   → NVIDIA/AMD Linux, unspecified: llamacpp (default) or ollama
   → HF safetensors / production serving: vllm
4. Model:
   → none specified: pull a small GGUF, then `harbor up`
     harbor pull unsloth/Qwen3.5-4B-GGUF:Q4_K_M
     harbor up
   → Ollama tag (`qwen3.5:4b`): harbor up ollama && harbor pull <tag>
   → HF GGUF (`org/repo[:quant]`): harbor pull <spec> && harbor up llamacpp
   → safetensors: harbor vllm model <org/repo> && harbor up vllm
   → DMR/MLX/oMLX: harbor models pull --source <src> <spec> (see models.md)
5. Verify: harbor ps, harbor models ls, harbor open

User wants a coding agent on a local model

1. Backend running or named with --backend (launch starts it if stopped)
2. harbor launch --backend <svc> --model <id> <tool>
   Common tools: codex, claude, grok, opencode
3. Need web search in the agent? add --web (not with claude)
4. Need a Boost quality/research pass? --workflow quickhop|deephop|autocheck
5. Codex + llama.cpp-family can fail on Responses API tool schema
   → use opencode with llamacpp, or Codex with ollama/vllm/dmr/mlx/omlx
See references/launch.md

User wants web search in chat

1. harbor up searxng
2. If webui was already running: harbor restart webui
3. harbor open  → web search is wired in Open WebUI

User wants code execution in chat

1. harbor up openterminal
2. harbor open  → Open WebUI gets a pre-wired Open Terminal connection

User wants voice in chat

1. harbor up speaches
2. If webui was already running: harbor restart webui

User wants to change the model

1. harbor ps  → which backend is up
2. ollama:     harbor pull <tag>  (pick in UI)
   llamacpp:   harbor pull <org/repo[:quant]>  (router discovers it)
   vllm:       harbor vllm model <org/repo> && harbor restart vllm
   dmr/mlx/omlx: harbor models pull --source <src> <spec>
3. Do not set llamacpp.model to "switch" models in router mode

User has GPU issues

1. NVIDIA: nvidia-smi
   AMD:    rocminfo or ls /dev/kfd /dev/dri
   Apple:  use dmr/mlx/omlx (host Metal), not a Linux CUDA image
2. NVIDIA toolkit: docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
3. docker logs harbor.<backend>  → CUDA / ROCm / OOM / no GPU
4. See references/troubleshooting.md

Initial setup

Prerequisites

docker --version         # 20.10+
docker compose version   # 2.23.1+
git --version

Linux: add the user to docker (sudo usermod -aG docker $USER) and re-login if docker needs sudo.

Install Harbor

Recommended:

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

Use | bash, not | sh. Then source ~/.bashrc (or ~/.zshrc) and:

harbor --version
harbor doctor

For an agent to install Harbor itself:

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

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

First start

harbor up

Expect harbor.llamacpp and harbor.webui healthy. First WebUI boot downloads embedding/Whisper weights; healthcheck grace can be several minutes.

harbor pull unsloth/Qwen3.5-4B-GGUF:Q4_K_M
harbor models ls
harbor open

Create the local Open WebUI admin account in the browser, pick the pulled GGUF, send a test message.

Core commands

Config

harbor config ls
harbor config search port
harbor config get webui.host.port
harbor config set webui.name "My AI"
harbor config update          # merge new keys from profiles/default.env
harbor env ollama             # list service overrides
harbor env ollama OLLAMA_NUM_PARALLEL 4

harbor defaults               # default is webui;llamacpp
harbor defaults add searxng
harbor defaults rm llamacpp
harbor defaults add ollama    # if the user wants Ollama as the default backend

harbor profile ls
harbor profile save mysetup
harbor profile use mysetup
harbor profile rm mysetup

Profiles are partial. Changes after use are not auto-saved.

Common stacks

# Default chat UI + GGUF backend
harbor up
harbor pull unsloth/Qwen3.5-4B-GGUF:Q4_K_M
harbor open

# Ollama registry models
harbor up ollama
harbor pull qwen3.5:4b
harbor open

# Web search + voice + code execution in Open WebUI
harbor up searxng speaches openterminal
harbor open

# Apple Silicon Metal
harbor up webui mlx
# or: harbor up webui dmr
# or: harbor up webui omlx

# Coding agent on a running backend
harbor launch --backend ollama --model qwen3.5:4b codex

LAN URL / QR: harbor url --lan webui, harbor qr webui. Temporary internet tunnel: harbor tunnel webui, then harbor tunnel down.