Getting Started

Install local-ai.run on macOS, Linux, or Windows. Pick the path that fits your environment: a single command for the fastest path, manual Docker Compose for full control, or an offline bundle for air-gapped machines.

Prerequisites

Before you install, make sure your machine meets these requirements:

Requirement	Minimum	Recommended
Docker	Docker Desktop (macOS / Windows) or Docker Engine + Compose v2 (Linux)	Latest stable
RAM	8 GB	16 GB+ for larger models
Free disk	~15 GB for images + base models	50 GB+ if you plan to install several models
OS	macOS 12+, Ubuntu 22.04+, Debian 12+, Windows 10/11 (WSL2)	—
Free host ports	`80` (Caddy), `5433` (Postgres), `11434` (Ollama), `8501` (RAG)	installer auto-detects port 80 conflicts

Docker is the only hard requirement. You do not need Python, Node, or any model runtime on the host — everything ships inside containers.

Quick install (recommended)

One command — the installer detects Docker, generates secrets, brings up the stack, and runs database migrations.

curl -fsSL https://get.local-ai.run/install.sh | bash

PowerShell (recommended):

irm https://get.local-ai.run/install.ps1 | iex

Or inside WSL2 (Ubuntu):

wsl -d Ubuntu
curl -fsSL https://get.local-ai.run/install.sh | bash

That's it. When the script finishes, open http://local-ai.localhost in your browser.

Per-machine reference (install & uninstall)

The install command is the same on each platform; the GPU it uses differs. Uninstall is one command too.

Machine	Install	Uninstall	GPU (Machine mode)
macOS — Apple Silicon (M1/M2/M3/M4)	`curl -fsSL https://get.local-ai.run/install.sh \| bash`	`curl -fsSL https://get.local-ai.run/uninstall.sh \| bash`	Apple Metal — fast
macOS — Intel (x86_64)	`curl -fsSL https://get.local-ai.run/install.sh \| bash`	`curl -fsSL https://get.local-ai.run/uninstall.sh \| bash`	None — runs on CPU (no GPU offload in Ollama)
Linux (Ubuntu/Debian)	`curl -fsSL https://get.local-ai.run/install.sh \| bash`	`curl -fsSL https://get.local-ai.run/uninstall.sh \| bash`	NVIDIA CUDA if present, else CPU
Windows 10/11	`irm https://get.local-ai.run/install.ps1 \| iex`	App → Settings, or `docker compose -f docker-compose.release.yml down -v`	NVIDIA CUDA (WSL2) if present, else CPU

On all platforms the installer asks Machine vs Docker and auto-installs host Ollama for Machine mode (falls back to the Docker container if that fails).

What the installer does

Checks for Docker, Docker Compose v2, RAM/disk, and a free port 80.
Creates ~/local-ai/ with a generated .env, Caddyfile, and compose file (random DJANGO_SECRET_KEY, RAG_API_KEY, WHISPER_API_KEY).
Asks where Ollama should run — Machine (host, GPU) or Docker (container) — see Ollama: Machine or Docker below.
If you chose Machine, auto-installs host Ollama (Homebrew/official app on macOS, official installer on Linux, winget/installer on Windows) and pulls llama3.1:8b + nomic-embed-text. If host setup fails, it falls back to the bundled Docker container.
Adds local-ai.localhost to /etc/hosts if your OS does not resolve .localhost automatically.
Runs docker compose up -d, waits for Django, and applies migrations.

Ollama: Machine or Docker

The model engine (Ollama) can run on your machine (host) or inside Docker. The installer asks at setup, and you can change it later in the app under Model Engines.

	🖥️ Machine (host)	🐳 Docker (container)
Speed	Fast — uses the GPU (Apple Metal / NVIDIA CUDA)	Slower — CPU only (no GPU in Docker on macOS)
Setup	Ollama auto-installed on the host	Nothing to install — runs in Docker
Models	Stored on the machine (`~/.ollama`)	Stored in a Docker volume
Best for	Machines with a good GPU (Apple Silicon, NVIDIA)	Quick / portable setups, or no GPU

Switch any time: in the app, go to Model Engines → "Ollama engine is running on…" → Switch. When pulling a model you can also choose Machine or Docker as the target.

Intel Macs: Ollama has no GPU offload there, so Machine mode still runs on CPU. On Apple Silicon and NVIDIA machines, Machine is much faster.

Want to inspect before running? Download the script first, read it, then run.

curl -fsSL https://get.local-ai.run/install.sh -o install.sh
cat install.sh
bash install.sh

Manual install (Docker Compose)

Prefer to clone the repo and run it yourself? You have two options: the clone setup script (recommended — does the env, Ollama choice, and docker compose up for you), or the step-by-step path below.

Clone & run with the setup script (recommended)

After cloning, run the setup script for your OS. It creates .env with generated secrets, asks where Ollama should run (Machine or Docker), installs/points to it, and starts the stack with docker compose up -d.

git clone https://github.com/360solutions-dev/local-ai.git
cd local-ai
./setup.sh

Works on macOS (Intel & Apple Silicon / M1) and Ubuntu / Linux.

git clone https://github.com/360solutions-dev/local-ai.git
cd local-ai
powershell -ExecutionPolicy Bypass -File .\setup.ps1

To tear it down later, use the matching uninstall script (--remove-ollama also removes host Ollama + downloaded models):

./uninstall.sh                 # stop stack + remove data volumes
./uninstall.sh --remove-ollama # also remove host Ollama + ~/.ollama
./uninstall.sh --keep-volumes  # keep chats / DB / models

powershell -ExecutionPolicy Bypass -File .\uninstall.ps1
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -RemoveOllama
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1 -KeepVolumes

macOS: don't clone into Documents, Desktop, or Downloads. macOS privacy (TCC) blocks Docker Desktop from bind-mounting folders under those paths, so docker compose up fails with mkdir /host_mnt/…: operation not permitted. Clone into your home directory instead (e.g. ~/local-ai), or grant Docker Desktop Full Disk Access in System Settings → Privacy & Security and add the path under Docker Desktop → Settings → Resources → File Sharing.

Step-by-step (do it yourself)

Prefer to inspect each step instead of the script? Follow these.

Clone the repository

git clone https://github.com/360solutions-dev/local-ai.git
cd local-ai

To pin to a specific release: git checkout v1.0.0.

Configure environment

cp .env.example .env

Open .env and set at minimum:

DJANGO_SECRET_KEY — a long random value, e.g. openssl rand -hex 32
POSTGRES_PASSWORD — strong password; keep DATABASE_URL in sync
RAG_API_KEY — shared secret used by Django and Next.js to call the RAG service
WHISPER_API_KEY — shared secret for the Whisper service
CORS_ALLOWED_ORIGINS — comma-separated origins allowed to call the Django API

See Configuration for the full reference. Never commit .env.

Start the stack

docker compose up --build -d

First build pulls base images and compiles the Next.js frontend. Allow several minutes.

Run database migrations

docker compose exec django python manage.py migrate

Pull Ollama models

Machine mode (host Ollama) — pull directly on the host:

ollama pull llama3.1:8b
ollama pull nomic-embed-text
ollama list

Docker mode (container Ollama):

docker compose --profile container-ollama exec ollama ollama pull llama3.1:8b
docker compose --profile container-ollama exec ollama ollama pull nomic-embed-text

Or pull from the app's Model Engines → Pull Model screen (choose Machine or Docker). Pick smaller models (llama3.2:3b, phi3:mini) on low-RAM machines.

Add the hosts entry

Caddy routes by hostname, so add the following line to your hosts file.

echo "127.0.0.1 local-ai.localhost api.local-ai.localhost" | sudo tee -a /etc/hosts

# Run Notepad as Administrator, then edit:
C:\Windows\System32\drivers\etc\hosts

# Add line:
127.0.0.1 local-ai.localhost api.local-ai.localhost

Open the app

You can now visit:

URL	What it is
`http://local-ai.localhost`	Main web app (Next.js, via Caddy)
`http://api.local-ai.localhost`	Django API (via Caddy)
`http://localhost:8501`	RAG document chat (Streamlit, optional)
`http://localhost:11434`	Ollama API (advanced users)

On first open, complete onboarding to create your admin account.

Offline / air-gapped install

For machines without internet access, prepare a bundle on a connected machine and transfer it.

1. Prepare on a connected machine

Build images, then save them as a single tarball:

docker compose build
docker compose pull

docker save -o local-ai-all-images.tar \
  caddy:2-alpine postgres:16-alpine ollama/ollama:latest \
  local-ai-backend:latest local-ai-frontend:latest \
  local-ai-rag:latest local-ai-whisper:latest

Back up the Ollama models volume so the offline machine has them ready:

docker run --rm \
  -v local-ai_ollama_data:/from \
  -v "$(pwd):/backup" \
  alpine tar czf /backup/ollama_data.tgz -C /from .

2. Transfer to the offline machine

Copy these files (USB, internal share, etc.):

The full project source tree (or a release zip).
local-ai-all-images.tar — place in docker-images/.
ollama_data.tgz — place at the project root.

3. Run the offline installer

chmod +x install.sh
./install.sh --offline

The script loads the tarballs, restores the Ollama volume, runs docker compose up -d, and applies migrations.

After install, verify with docker compose ps and docker compose exec ollama ollama list.

Updating to a new version

Update from inside the app: Settings → Advanced → Check for Updates → Install Update.

Or manually:

docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d

Uninstall

Remove containers, project images, volumes, the install folder, and the local-ai command in one command (asks before deleting, and separately before removing host Ollama):

curl -fsSL https://get.local-ai.run/uninstall.sh | bash

cd $env:USERPROFILE\local-ai
docker compose -f docker-compose.release.yml down -v --remove-orphans

Flags (macOS/Linux): --keep-volumes (keep chats/models), --keep-ollama (don't touch host Ollama), --yes (no prompts).

Fix host Ollama (macOS)

If Machine mode can't start Ollama, or you see a TLS error (tls: failed to verify certificate: SecPolicyCreateSSL) when pulling models, do a clean reinstall (works on Intel and Apple Silicon):

pkill -9 -f ollama 2>/dev/null
brew uninstall --cask --force ollama-app ollama 2>/dev/null; brew uninstall --force ollama 2>/dev/null
rm -rf /Applications/Ollama.app
brew install --cask ollama
xattr -dr com.apple.quarantine /Applications/Ollama.app 2>/dev/null
nohup /Applications/Ollama.app/Contents/Resources/ollama serve >/tmp/ollama.log 2>&1 &
sleep 5 && curl -s http://localhost:11434/api/version

When the last command prints {"version":"..."}, re-run the installer — it detects the running Ollama and uses Machine mode.

Next steps

Configuration

Tune .env variables — ports, Whisper model, host Ollama, image tags.

Troubleshooting

If something doesn't start — port conflicts, GPU, disk, large uploads.