LocalPilot

Local AI, Made Simple.

Find an AI that fits your computer, set it up safely, and help you use it.

Website • Documentation • PyPI • Report Bug

🌟 Why LocalPilot?

Running local AI shouldn't require configuring build flags, figuring out CUDA or Metal layer offloading, calculating KV-cache bytes, or manually nursing broken environment variables.

LocalPilot is a friendly, hardware-aware Python application that guides you from discovery to chat. It inspects your real hardware capabilities, scores models based on verified compatibility, sets up runtimes with safe defaults, and monitors resource usage in a calm, full-screen terminal dashboard or intuitive CLI.

✨ Key Features

• 🧠 Hardware-Aware Recommendation: Evaluates CPU, RAM, GPU, Apple Silicon Unified Memory vs. discrete VRAM, and storage budgets. Filters out incompatible models before you waste bandwidth.
• 🧭 3-Axis Execution Architecture: Decouples model computation into three orthogonal dimensions:
  • Inference Backends: llama.cpp (GGUF, Metal, CUDA), vLLM (advanced Linux+GPU).
  • Managed Execution Services: Ollama, LM Studio / llmster, and Docker Model Runner.
  • Deployment Methods: Direct isolated worker processes (direct_worker), local API services (local_api_service), and containers.
• 🛡️ External Service & Data Protection:
  • Respects external daemons: unloads models from memory (keep_alive=0 / /v1/models/unload) without killing shared background services.
  • Reference-counted storage protects your model files and never deletes unowned files.
• 📦 Multi-Scope Installation: Choose between Application-Isolated (default, no root needed), User-Space (~/.local/bin), or System-Wide (/usr/local/bin).
• 💻 Dual Interface:
  • Interactive TUI: A beautiful full-screen dashboard powered by Textual.
  • Fast Scriptable CLI: Clean, structured CLI commands powered by Typer and Rich.
• 📝 Comprehensive Observability: Structured event logs, audit checkpoints before destructive actions, and support bundle diagnostics.

🚀 Installation & Quick Start

Choose the method that fits your computer:

Option 1: Automated Shell Installer (Recommended for Non-Technical Users)

No need to configure Python virtual environments or paths manually:

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

Option 2: With pipx (Recommended for Python CLI Users)

pipx install localpilot

Option 3: With pip or uv

pip install localpilot
# or
uv tool install localpilot

👉 For advanced flags, custom scopes, and uninstallation instructions, see the Installation Guide.

🧠 New to Local AI? Read This First

If terms like inference backends, weights, VRAM, Ollama, or Docker seem confusing, read our friendly Beginner's Guide to Local AI.

In short:

• Model Weights: A large data file containing learned knowledge (like a book).
• Inference Backend (e.g. llama.cpp, vLLM): The computational engine that does the math on your CPU or GPU (like the reader).
• Execution Service (e.g. Ollama, LM Studio, Docker): Optional background daemons that manage models and local APIs.
• Why LocalPilot?: You don't have to manually match engines, calculate memory bytes, or troubleshoot Docker. LocalPilot inspects your machine, selects the optimal plan automatically, and reuses any tools you already have installed!

🎮 Usage Guide

Launch the Terminal Dashboard (TUI)

Simply type:

localpilot

Use keyboard shortcuts to navigate:

• d Find compatible models
• i View installed models
• r View running models & resource usage
• s Inspect managed storage
• a Activity and decision history
• q Exit

Command-Line Interface (CLI)

1. Inspect Your Computer's Hardware

localpilot doctor

Outputs CPU cores, system RAM, safe memory budget, GPU accelerators (CUDA/Metal), and discovered runtimes.

2. Discover Compatible Models

localpilot discover

Filter by task or search query:

localpilot discover --task coding
localpilot discover -q "llama"

3. Guided Model Setup

localpilot setup <candidate-id>

LocalPilot checks whether supporting software (such as Ollama or llama.cpp) is already present. If found, it calmly uses it:

"LocalPilot found supporting software already installed. We can use it to run this model."

4. Run & Chat

localpilot run <model-id-or-install-id>

5. Monitor Running Models

localpilot running

6. Storage Inspection & Safe Removal

# View storage breakdown
localpilot storage

# Safely remove a model without affecting other installations
localpilot remove <installation-id>

📐 Architecture Overview

Application Services (CLI / TUI / Setup / Chat)
                    │
                    ▼
          ┌───────────────────┐
          │   ExecutionPlan   │
          └─────────┬─────────┘
                    │
   ┌────────────────┼────────────────┐
   ▼                ▼                ▼
Backend          Service         Deployment
llama.cpp        Ollama          direct_worker
vLLM             LM Studio       local_api_service
                 Docker Runner   container

For full details on platform compatibility and supported backend/service combinations, see the Support Matrix.

👤 Author & Maintainer

Mohamed Fouad Fakhruldeen
Creator & Maintainer of LocalPilot. Working across PMO governance, AI systems, and agile enterprise operating systems.

• 🌐 Website: fakhr.me
• 💼 LinkedIn: linkedin.com/in/fakhruldeen
• 🐙 GitHub: @fakhruldeen
• 📬 Email: fakhruldeen@gmail.com

⚠️ Disclaimer

📄 License

This project is licensed under the terms of the GNU General Public License v3 (GPLv3). See the LICENSE file for details.