GarudAI — Installation Guide

1. Before you start

Requirement	Minimum	Recommended
Operating system	64-bit Windows 10/11, modern Linux, or macOS 12+	Windows 11 or Ubuntu 22.04+
RAM	8 GB	16 GB
Free disk	50 GB	100 GB+ (for recordings)
Internet	Required for first install	—

You do not need to install Docker yourself — each installer sets it up for you. After installing, open the dashboard at http://localhost:3010.

🪟

Windows

One-click installer

Download .exe

🐧

Linux

Ubuntu, Debian, Fedora, RHEL, Arch, SUSE

Download .run

macOS

Intel & Apple Silicon

Download .run

2. Windows

Download GarudAI-Setup-v3.1.exe.
Double-click it. If Windows SmartScreen appears, click More info → Run anyway.
The wizard checks your system and installs WSL2 and Docker Desktop if they're missing (a restart may be required — the installer resumes automatically).
It downloads the AI engine (~3.6 GB) and starts GarudAI.
When finished, click Open GarudAI Dashboard (or visit http://localhost:3010).

GarudAI runs in the background and starts with Windows. Use the GarudAI tray icon (bottom-right) to start/stop services or open the dashboard.

3. Linux

The same installer works on all major distributions — it auto-detects your package manager and installs Docker for you.

Easiest — single self-extracting file

# Download, make executable, run
curl -fLO https://licensestore.garudai.com/downloads/GarudAI-linux-v3.1.run
chmod +x GarudAI-linux-v3.1.run
sudo ./GarudAI-linux-v3.1.run

That one file unpacks itself and installs everything. (Equivalent: sudo sh GarudAI-linux-v3.1.run.)

Alternative — .tar.gz

curl -fLO https://licensestore.garudai.com/downloads/GarudAI-linux-v3.1.tar.gz
tar -xzf GarudAI-linux-v3.1.tar.gz
cd GarudAI-linux-v3.1
sudo ./install.sh

Per-distribution notes

The command above is identical everywhere; Docker is installed automatically. If your distro blocks the automatic Docker install, install Docker first using the official package, then re-run sudo ./install.sh:

Distribution	If Docker install is needed manually
Ubuntu / Debian / Mint	`sudo apt update && sudo apt install -y docker.io docker-compose-plugin`
Fedora	`sudo dnf install -y docker docker-compose-plugin && sudo systemctl enable --now docker`
RHEL / CentOS / Rocky / Alma	`sudo dnf install -y docker docker-compose-plugin && sudo systemctl enable --now docker`
openSUSE	`sudo zypper install -y docker docker-compose && sudo systemctl enable --now docker`
Arch / Manjaro	`sudo pacman -S --noconfirm docker docker-compose && sudo systemctl enable --now docker`

If you prefer wget: wget https://licensestore.garudai.com/downloads/GarudAI-linux-v3.1.tar.gz

GPU (optional): GarudAI runs in CPU mode by default. To use an NVIDIA GPU, install the NVIDIA Container Toolkit for your distro, then change the compute mode under Settings → Compute.

4. macOS

Apple Silicon (M1/M2/M3/M4): GarudAI's AI engine is built for Intel and runs under emulation on Apple Silicon — it works, but AI detection is slower. For production, a Windows or Linux PC is recommended. Intel Macs run it natively.

First, install Docker Desktop for Mac (choose Apple Silicon or Intel to match your Mac). If you have Homebrew, the installer can do it for you. Then:

Easiest — single self-extracting file (Terminal)

curl -fLO https://licensestore.garudai.com/downloads/GarudAI-mac-v3.1.run
xattr -dr com.apple.quarantine GarudAI-mac-v3.1.run   # clear the download flag
chmod +x GarudAI-mac-v3.1.run
./GarudAI-mac-v3.1.run

Run it as your normal user (no sudo) — Docker Desktop is per-user.

Alternative — .tar.gz (double-click)

Download GarudAI-mac-v3.1.tar.gz and double-click to unzip.
Open the GarudAI-mac-v3.1 folder and double-click install.command. (If macOS blocks it: right-click → Open → Open.)
It installs/starts Docker Desktop, downloads the AI engine, and opens the dashboard.

Manage it with garudai start | stop | status | logs | open (or ~/GarudAI/garudai …). In Docker Desktop → Settings, enable "Start Docker Desktop when you log in" so it returns after a reboot.

5. First login

Open http://localhost:3010.
Log in with the admin account created on first run. On Linux/macOS, find the generated password with garudai logs backend (look for the admin password line); on Windows it's shown in the setup log.
Change the password in Settings, then add your cameras (the setup wizard guides you).

6. Troubleshooting — all platforms

Problem	Fix
Dashboard won't load	Wait 1–2 minutes after install (images start up). Windows: tray → Status. Linux/macOS: `garudai status` — every service should say "Up". Then `garudai logs`.
Cameras not auto-discovered	In Add Camera → ONVIF, type your network range (e.g. `192.168.1.0/24`) and scan again, or use "Add by IP" and enter the camera's IP + login. Many budget cameras use ONVIF port `8899` — GarudAI handles that automatically.
"Connect failed" on a camera	Use the camera's ONVIF login (often `admin` + the password from the camera's app), not the Wi-Fi password.
Forgot the admin password	It's printed once on first run: `garudai logs backend` (Linux/macOS) or the Windows setup log. Then change it in Settings.

7. Troubleshooting — Linux

Symptom	Cause & fix
`install.sh` exits "Please run as root"	Run with `sudo`: `sudo ./install.sh` (or `sudo ./GarudAI-linux-v3.1.run`).
`permission denied … /var/run/docker.sock` when using `garudai`	Your user isn't in the `docker` group. Run `sudo usermod -aG docker $USER`, then log out and back in. (Or just use `sudo garudai …`.)
"Cannot connect to the Docker daemon"	Docker isn't running: `sudo systemctl enable --now docker`.
Docker was installed via snap (Ubuntu) and mounts/compose fail	Snap-confined Docker can't read `/opt` mounts. Remove it and use the official package: `sudo snap remove docker` then `curl -fsSL https://get.docker.com \| sudo sh`, then re-run the installer.
Fedora / RHEL / Rocky / Alma: backend/mediamtx can't read mounted files (SELinux)	SELinux blocks bind mounts. Relabel the install dir: `sudo chcon -Rt svirt_sandbox_file_t /opt/garudai` then `garudai restart`. (To confirm it's SELinux: `sudo setenforce 0` temporarily and retry.)
A service won't start — "port is already allocated"	Another program uses one of GarudAI's ports (3010, 8000, 9000, 9001, 9090, 3001, 6379, 5434, 1935, 8554, 8888, 8889, 9997, 16686, 4317). Find it: `sudo ss -tlnp \| grep -E ':(3010\|8000\|9000\|6379)'` and stop that program.
Dashboard works on the PC but not from other devices on the LAN	Open the ports in your firewall: ufw: `sudo ufw allow 3010/tcp && sudo ufw allow 8000/tcp` firewalld: `sudo firewall-cmd --add-port=3010/tcp --add-port=8000/tcp --permanent && sudo firewall-cmd --reload`
Installer says "requires x86_64" (Raspberry Pi / ARM server)	GarudAI's AI images are 64-bit Intel/AMD only. ARM (aarch64) boards are not supported — use an x86_64 PC or mini-PC.
"no space left on device" while loading images	Docker stores images under `/var/lib/docker`. Free up space (need ~10 GB for images) or move Docker's data-root to a larger disk.
Services restart / get OOM-killed	Not enough RAM. GarudAI needs 8 GB. Close other apps or add RAM; reduce the number of active cameras.
Behind a corporate proxy — downloads fail	Configure Docker's proxy (`/etc/systemd/system/docker.service.d/http-proxy.conf`) and export `https_proxy` before running the installer.
Start GarudAI manually / on boot	It's a systemd service: `sudo systemctl start garudai` / `… enable garudai`. Or `garudai start`.

8. Troubleshooting — macOS

Symptom	Cause & fix
macOS won't open `install.command` / `.run` ("unidentified developer")	Gatekeeper quarantine. Either right-click the file → Open → Open, or clear the flag: `xattr -dr com.apple.quarantine GarudAI-mac-v3.1.run`
Apple Silicon: containers crash / "exec format error" / "rosetta error"	Enable amd64 emulation in Docker Desktop → Settings → General → tick "Use Rosetta for x86_64/amd64 emulation". Install Rosetta first if needed: `softwareupdate --install-rosetta --agree-to-license`.
Detection very slow on Apple Silicon	Expected — amd64 under emulation. For production use a Windows or Linux PC. Intel Macs run natively.
Services keep restarting / very sluggish	Docker Desktop's memory is too low. Settings → Resources → set Memory to 8 GB (or more) and CPUs to 4+.
Installer says Docker isn't installed and you have no Homebrew	Install Docker Desktop manually (matching your chip), open it once, then re-run the installer.
"Cannot connect to the Docker daemon"	Docker Desktop isn't running. Open it, wait for "Docker Desktop is running", then run `garudai start`.
`garudai: command not found`	On Apple Silicon `/usr/local/bin` may be read-only. Use `~/GarudAI/garudai …`, or add an alias: `echo 'alias garudai="$HOME/GarudAI/garudai"' >> ~/.zshrc && source ~/.zshrc`
A service won't start — port already in use	Find the conflicting app: `lsof -i :8000` (or :9000, :6379, :3010) and quit it.
"mounts denied" / file-sharing error	Keep GarudAI at the default `~/GarudAI` (inside your home folder, which Docker Desktop shares). If you moved it, add its path under Docker Desktop → Settings → Resources → File Sharing.
GarudAI doesn't come back after reboot	Enable Docker Desktop → Settings → General → "Start Docker Desktop when you log in." Containers auto-restart once Docker is up.
macOS firewall prompts about incoming connections	Click Allow (needed for the local dashboard and camera streams).

Still stuck? Email support@garudai.com with the output of garudai logs (Linux/macOS) or the Windows setup log.