Installation & Setup Guide

✨

Never Used a Terminal Before?

It's as easy as copy & paste

You do not need to be a developer to run LocalPilot. The "terminal" is just a text window built into every Mac and Linux computer. Here is how to open it in 5 seconds:

🍏 On macOS (Apple MacBooks, iMac, Mac Mini)

Press Cmd ⌘ + Space on your keyboard to open Spotlight Search.
Type Terminal and press Enter ↵.
A friendly black-or-white text window will open. You're ready!

💻 On Linux (Ubuntu, Debian, Fedora, Mint)

Press Ctrl + Alt + T on your keyboard.
Or press your Super (Windows) key, type Terminal, and press Enter ↵.
Your terminal shell will appear immediately.

★

Method 1: 1-Click Installer (Recommended)

Novice Friendly

No need to create virtual environments, configure paths, or install complex libraries. Copy this command, paste it into your Terminal window, and hit Enter ↵:

curl -fsSL https://raw.githubusercontent.com/fakhruldeen/LocalPilot/main/install-localpilot.sh | bash

🔍 What this command does behind the scenes (Plain English):

Verifies Python: Checks that Python 3.11+ is installed on your computer.
Creates an Isolated Sandbox: Sets up LocalPilot inside your private user folder (~/.local/share/localpilot) so your system files remain completely untouched.
Creates a Shortcut: Adds a launcher in ~/.local/bin so you can simply type localpilot from anywhere.
Zero Root Required: It will never ask for your administrator password (sudo) and will never modify system files.

Your First 60 Seconds with LocalPilot

Once the installer finishes (usually in 10-20 seconds), here is how to enjoy your new private AI:

Step 1: Check Health

localpilot doctor

Audits your CPU, RAM, and graphics memory in 2 seconds and verifies exact compatibility.

Step 2: Open Dashboard

localpilot

Opens the colorful full-screen interactive terminal dashboard to browse models and inspect memory.

Step 3: Start Chatting

localpilot chat llama3.2:3b

Downloads the compact 3B model and launches an instant offline private conversation!

Alternative Methods (pipx or pip)

⚠️ Prerequisite: Python & Pip Must Be Installed Already

Unlike the 1-click curl installer (which can bootstrap everything), installing via pipx or pip requires that Python (version 3.10 or newer) and pip are already set up on your machine.

Verify if you have them:

$ python3 --version

$ pip --version

Need to install Python & pip first?
• Ubuntu / Debian: sudo apt update && sudo apt install -y python3 python3-pip python3-venv pipx
• macOS: brew install python pipx (requires Homebrew)

📦 With pipx (Isolated App)

If you have pipx installed, this installs LocalPilot inside an isolated environment and links the CLI globally:

pipx install localpilot

🐍 With standard pip

For developers working inside an existing active virtual environment:

pip install localpilot

Comprehensive Step-by-Step Guide After Installation

Follow these 6 detailed steps to go from a fresh installation to running private, offline conversations with complete confidence:

Step 1 • Hardware Diagnostics Duration: ~3 seconds

Audit Your Computer's Hardware

Before downloading models, run the built-in diagnostic doctor. It checks your CPU cores, free RAM, GPU acceleration (Metal on Mac, CUDA on Linux), and ensures there are no conflicting background services.

$ localpilot doctor

Step 2 • Discovery & Compatibility Duration: Instant

Find Which Models Fit Your RAM Safely

Run discovery to see a ranked list of models specifically compatible with your machine. LocalPilot automatically excludes models that are too large to prevent your operating system from freezing.

$ localpilot discover --task chat

Step 3 • Guided Setup & Verification Duration: 2 to 4 minutes

Download & Verify Your First Model

Download your chosen model. LocalPilot streams the real download progress, verifies the SHA-256 cryptographic fingerprint, configures execution parameters, and tests real prompt inference before marking it ready:

$ localpilot setup llama3.2:3b

Step 4 • Private Chatting 100% Offline

Start Your Offline Conversation

You can converse directly via the CLI, or open the visual terminal dashboard:

$ localpilot chat llama3.2:3b # Direct interactive chat

$ localpilot tui # Full graphical terminal dashboard

Step 5 • Navigation & Exiting Clean Memory Release

In-Chat Commands & Clean Exit

Inside the chat session, type /help to see shortcut options. When you want to exit, type /exit or press Ctrl + C. LocalPilot terminates the background inference process and returns 100% of the RAM back to your operating system immediately.

Step 6 • Storage Management Total User Control

Review & Reclaim Disk Space

See what models you have downloaded and how much storage they occupy:

$ localpilot storage # Breakdown of storage usage

$ localpilot remove llama3.2:3b --delete-files # Cleanly delete model files

Updating Models & Catalogs Locally

Can you update models and fetch newer revisions locally? Yes! Here is how model updates work:

1. Refresh Catalog

Running localpilot discover contacts verified source registries (Ollama library and Hugging Face) and caches updated model metadata in your local SQLite store.

2. Pull Model Updates

To pull a newer revision of an installed model, run localpilot setup <model-id>. If using Ollama directly, you can also run ollama pull <model-id>.

3. Atomic Staging & Rollback

LocalPilot stages model updates in a temporary backup folder first. If the new file fails inference or has an invalid hash, your existing working model is kept intact with zero downtime.

Application Updates & Clean Removal

🔄 Update LocalPilot Application

To check PyPI for new releases of LocalPilot and upgrade in place:

localpilot self update

🧹 1-Command Clean Removal

If you ever wish to uninstall LocalPilot completely, run:

localpilot self uninstall --purge-models

Removes the application sandbox, launcher shortcuts, and all stored model weights. Leaves zero background traces on your machine.