Installation

This page is the complete install guide: official packages, the CLI one-liner, and a source build of the gateway + WebUI.

Related:

• First session in the terminal: CLI quickstart
• One-liner only: CLI install
• Product map: Capabilities
• Site: navin.live/download · navin.live/en/docs

After any official install you should have two commands:

Do not use navin tui or navin agent as the entry point.

1. Desktop packages (recommended)

Download from navin.live/download.

User data stays in ~/.navin (or %USERPROFILE%\.navin on Windows) across upgrades: config, workspaces, memory, projects.

Windows SmartScreen ("Windows protected your PC") can appear on a correctly signed setup. Microsoft checks the publisher and the reputation of that exact file hash. Navinspire as signer does not clear it on the first downloads. An EV certificate no longer bypasses it. Keep More info → Run anyway until reputation builds, or install from the Microsoft Store when that listing exists. To check the file you actually downloaded:

Get-AuthenticodeSignature ".\Navin-Desktop-2.0.1-windows-x64-setup.exe" |
  Format-List Status, StatusMessage, SignerCertificate

Status should be Valid. That confirms the signature, not SmartScreen. The same check, including navin.exe / Navin.exe / NavinUpdater.exe inside the installer, is packaging/windows/verify-windows-signatures.ps1.

If navin or navin-cli is missing from PATH after a DMG or portable install:

navin install-cli
navin install-cli --force

Then:

cd your-project
navin-cli
navin .
navin --version
navin doctor

2. Official CLI one-liner

The script reads the official releases.json. It prefers a CLI archive when published, otherwise it extracts the desktop package. It writes navin and navin-cli to the user PATH. No sudo on Linux. Default prefix: ~/.local.

Linux, macOS, WSL:

curl https://navin.live/install -fsS | bash

Windows PowerShell:

irm 'https://navin.live/install?win32=true' | iex

cd your-project
navin-cli
navin --version
navin doctor
navin status

Linux arm64: use navin.live/download until a CLI tarball is listed.

Environment overrides:

Local site (developers)

When the marketing site runs on this repo (localhost:3100) and you have prepared local archives:

make local-releases
curl http://localhost:3100/install -fsS | bash

/install then serves files from this repository and does not hit production S3.

3. First configuration

In navin-cli, Ctrl+G → Providers: add a key (OpenRouter, OpenAI, Anthropic, …) or a local apiBase (Ollama http://127.0.0.1:11434/v1). Then Models: add a configuration and set it active.

Or:

navin onboard

Env keys (OPENROUTER_API_KEY, …) are honored and are not written to config.json.

This tree is BYOK only. Add keys in Ctrl+G → Providers. There is no Navin managed provider and no navin.live account on main.

Config file: ~/.navin/config.json. Same file for navin-cli and the desktop.

4. Build from source (gateway + WebUI)

Use this when you clone the repository and want to run or change Navin locally.

make install installs missing system packages when it can (apt on Debian/Ubuntu, dnf/yum on Fedora/RHEL, pacman on Arch, zypper, Homebrew on macOS), then the Python backend and the WebUI.

Prerequisites

If you skip system install (NAVIN_SKIP_SYSTEM=1 or --no-system):

• Python 3.11 or newer
• Make
• Git
• Node.js 18+ and npm
• Linux / macOS: rustup if you need the native sandbox (make native)

Two commands

git clone https://github.com/navinspire-ai/navin-agi.git
cd navin-agi
make install
make start

Or the same with scripts:

sh scripts/install.sh
sh scripts/start.sh

One shot (install + start):

sh scripts/start.sh --install

This is dev:

• Vite hot reload: http://localhost:5173/
• the gateway (health + API). The same gateway serves the production WebUI from navin/web/dist at http://localhost:8765/ (or channels.websocket.port)

make stop
# or: sh scripts/stop.sh

Front / backend

Make and scripts accept the same scopes:

make start backend
make start front
make restart
make status
make logs

Native helpers (Linux / macOS), after make install:

make native

Vite proxies /api, /webui, /auth and the WebSocket to the gateway. If the gateway is not on 8765:

NAVIN_API_URL=http://127.0.0.1:8766 npm run dev

Docker (this repo)

No third-party Navin image. Build from https://github.com/navinspire-ai/navin-agi (this tree):

docker compose up navin-gateway

The image installs the navin CLI and serves the bundled WebUI. Gateway health defaults to 18790, WebUI to 8765. Config: ~/.navin mounted into the container.

Use the source CLI

From the navin-agi clone, after install, you can launch the CLI with the venv binary. No need to activate the venv:

cd /path/to/navin-agi
.venv/bin/navin-cli

Windows:

cd \path\to\navin-agi
.venv\Scripts\navin-cli

Or activate the venv, then run it from any project folder:

source .venv/bin/activate   # Windows: .venv\Scripts\activate
cd /path/to/your-project
navin-cli
navin doctor

Ports

navin ports
navin ports check

See Ports.

Always-on gateway

navin gateway --background
navin gateway status
navin gateway logs
navin gateway install-service

Long-running agent · Deploy the gateway

5. Uninstall

• Desktop: use the OS uninstaller.
• CLI prefix: remove ~/.local/bin/navin, ~/.local/bin/navin-cli and ~/.local/share/navin (or your NAVIN_PREFIX).
• User data is not deleted automatically. Remove ~/.navin only if you want to wipe config, chats and workspaces.

navin cache --clear

Does not delete chats, config, or workspaces.

6. Troubleshooting

navin doctor
navin --version
navin ports check

More: CLI troubleshooting · Start without a technical background