Technical Architecture & CLI Manual

Hexagonal Clean Architecture (Ports & Adapters)

LocalPilot is engineered using strict domain-driven hexagonal boundaries. The core business rules and verification logic have zero dependencies on CLI frameworks, TUI libraries, or specific runtime binaries.

1. Presentation Layer (CLI & TUI Drivers)

User Interface Inbound Ports

Typer CLI Command routing, Rich terminal formatting, JSON & plaintext pipes

localpilot

Textual TUI Hub Reactive full-screen dashboard, live log streams, F1 / ? keybinding help

localpilot tui

▼ invokes use cases through typed execution boundaries

2. Application Layer (Use Cases & Orchestration)

Transactional Workflows

SetupWorkflow Discover → Pull → Test

RuntimeService Lifecycles & Probes

UpdateWorkflow Atomic Staging

JobManager Async Task Tracking

ActivityService Redacted Audit Trails

▼ enforces pure domain invariants, safety rules & scoring policies

3. Domain Core (Zero External Dependencies)

Pure Python Logic

CompatibilityPolicy

Calculates RAM/VRAM offload ratio, reserves 512 MB OS buffer, and excludes oversized weights.

ScoringPolicy

Multi-factor weighting: fit confidence, generation speed, quantization quality, and platform acceleration.

ExecutionPlan

Immutable 3-axis execution triplet: Backend × Managed Service × Deployment Method.

VerifiedState

Evidence-backed state transitions: UNTESTED → DOWNLOADED → TESTED_HERE (verified inference).

▼ drives infrastructure via abstract SPI ports (outbound interfaces) ▼

Platform Adapters Hardware SPI

• Linux / Darwin OS Probes
• Apple Metal & Unified Memory
• NVIDIA CUDA & AMD ROCm
• Loopback Port Scanner

Source Adapters Catalog SPI

• Ollama Model Registry Client
• Hugging Face Hub (GGUF Weights)
• Curated Local Seed Catalog
• SHA-256 Digest & Length Validator

Runtime & Storage Execution SPI

• llama.cpp Direct Subprocess Runner
• Ollama Local REST API Client
• LM Studio / llmster Client
• Reference-Counted Storage & SQLite

📐 View Monospace ASCII Architectural Blueprint Expand Raw ASCII

┌────────────────────────────────────────────────────────────────────────┐
│                        PRESENTATION LAYER                              │
│       Typer CLI (localpilot)     │       Textual TUI (Visual Hub)      │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        APPLICATION LAYER                               │
│  SetupWorkflow  │  UpdateWorkflow  │  JobManager  │  ActivityService   │
└─────────────────────────────────┬──────────────────────────────────────┘
                                  ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          DOMAIN LAYER                                  │
│  CompatibilityPolicy │ ScoringPolicy │ ExecutionPlan │ VerifiedState   │
└──────────────┬──────────────────┬──────────────────────┬───────────────┘
               ▼                  ▼                      ▼
┌──────────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐
│   PLATFORM ADAPTERS  │ │  SOURCE ADAPTERS │ │    RUNTIME ADAPTERS     │
│  Linux / Darwin      │ │  Ollama Registry │ │  llama.cpp runner       │
│  Hardware Inspector  │ │  HuggingFace Hub │ │  Ollama API Client      │
│  Metal / CUDA check  │ │  Local Seed DB   │ │  LM Studio Client       │
└──────────────────────┘ └──────────────────┘ └─────────────────────────┘

localpilot.domain

Pure Python entities: HardwareSnapshot, ExecutionPlan, CompatibilityCheckResult, scoring heuristics, and evidence-based state transitions.

localpilot.application

Transactional use cases: multi-step model staging, atomic download rollback, non-destructive inventory reconciliation, and background job state.

localpilot.runtimes

Isolated infrastructure adapters: socket probes, subprocess launchers, PID isolation, and HTTP API clients with strict timeouts.

The 3-Axis Execution Dispatch Engine

Most naive tools treat local AI as a monolithic "runtime" string (e.g. just "ollama" or "llamacpp"). LocalPilot decomposes execution into three mathematically orthogonal dimensions:

AXIS A Compute

Inference Backend

The raw computation library that loads tensors into memory and executes matrix multiplication on CPU or GPU.

• llama.cpp (GGUF)

• vLLM (Advanced)

• service-managed

AXIS B Service

Execution Service

The supervisor daemon or manager responsible for model residency, caching, and serving API requests.

• Ollama

• LocalPilot Managed

• LM Studio / llmster

• Docker Model Runner

AXIS C Process

Deployment Method

The process boundary and sandboxing model through which LocalPilot interfaces with the service.

• Direct Worker Subprocess

• Local Loopback HTTP API

• Container Runtime

Engineering Dispatch Rule: "LocalPilot resolves actual adapters from the full execution triplet. An Ollama plan connects to Ollama's HTTP daemon; a standalone GGUF plan routes to direct llama.cpp. It will never silently route LM Studio or vLLM to llama.cpp."

Complete CLI Command & Argument Reference

The localpilot binary is built with Typer and Rich, supporting structured terminal tables, plaintext scripts (--plain), and JSON piping (--json).

localpilot [COMMAND] Interactive Default

When invoked without subcommands, opens the numbered interactive home menu or full-screen dashboard.

$ localpilot tui # Direct launcher for the Textual terminal GUI

localpilot doctor Hardware Diagnostics

Runs non-invasive hardware probing: CPU architecture, available cores, physical RAM, GPU acceleration (Metal / CUDA / ROCm), storage headroom, and port availability.

$ localpilot doctor

localpilot discover [OPTIONS] Model Sizing & Ranking

Queries local and registry catalogs, filters out models that exceed available memory, scores candidates using the agreed scoring policy, and selects the recommended execution plan.

Option / Flag	Type	Description
--task	string	Filter by task category: `chat`, `coding`
-q, --query	string	Case-insensitive search across model name, family, or ID
--plain	flag	Output plain space-separated text for shell scripts
--json	flag	Emit full candidate and execution plan metadata in JSON

$ localpilot discover --task chat --query llama

localpilot setup <candidate_id> [OPTIONS] Guided Installation

Executes guided installation: validates compatibility, downloads real weight artifacts, verifies SHA-256 hashes, provisions local runtime adapters, and performs verified smoke inference.

Argument / Option	Type	Description
<candidate_id>	string	Target model candidate ID (e.g. `llama3.2:3b`)
-y, --yes	flag	Accept proposed execution plan without interactive confirmation
--scope	string	Installation boundary: `isolated` (default), `user`, `system`

$ localpilot setup llama3.2:3b --yes

localpilot chat <model_id> [OPTIONS] Interactive Dialogue

Starts a live, streaming chat session in your terminal with real-time token rendering. If the model is not currently running, LocalPilot automatically activates the selected execution backend, verifies readiness, and manages graceful cleanup upon exit (Ctrl + C or /exit).

$ localpilot chat llama3.2:3b # Chat with verified local model

$ localpilot chat qwen2.5-coder:7b --temperature 0.2 # Low temperature for coding precision

localpilot run | stop <model_id> Process Supervision

run launches a headless model instance or server in the background. stop performs a non-destructive shutdown. Crucially, LocalPilot respects ownership: if an external daemon (like Ollama system service) was already running before, LocalPilot will unbind without terminating external user processes.

$ localpilot run llama3.2:3b # Start model instance in background

$ localpilot stop llama3.2:3b # Safely unload model and release memory

localpilot installed | running Inventory & Probes

installed lists models present on disk with their verification stage (TESTED_HERE), size, and runtime. running probes live PID/service instances. Supports --plain and --json.

$ localpilot installed --json

$ localpilot running --plain

localpilot guide | docs [OPTIONS] Built-in Knowledge System

Access comprehensive documentation right in the terminal. guide provides chapter-by-chapter tutorials tailored for beginners or developers. docs outputs deep engineering references for memory math, storage structures, and security boundaries.

Command / Option	Description
guide --audience novice\|technical	Filter the guide for plain-English beginners or deep technical users
guide -s, --search <query>	Search across all guide topics and answers directly from terminal
docs --topic <topic>	Inspect deep technical manuals: `overview`, `technical`, `storage`, `compatibility`

$ localpilot guide --interactive # Open interactive chapter navigator

$ localpilot docs --topic technical --plain # Pipe technical architecture to pager

localpilot logs | activity | support Audit & Diagnostics

LocalPilot features automatic privacy redaction: API tokens, bearer keys, and user personal file paths are scrubbed in memory before writing to disk. activity shows installation/lifecycle events; support generates an anonymized diagnostic bundle for GitHub issues.

$ localpilot logs --lines 50 # Tail redacted runtime logs

$ localpilot activity --json # Audit trail of operations

$ localpilot support # Generate privacy-redacted debug archive

localpilot storage | remove <id> Space Reclamation

storage outputs total gigabytes used across model weights, SQLite databases, and logs. remove <id> safely deletes weights without touching third-party files.

$ localpilot storage

$ localpilot remove llama3.2:3b --delete-files -y

localpilot self update | uninstall Application Lifecycle

self update queries PyPI and performs safe in-place upgrades. self uninstall cleanly purges symlinks and virtual environments with optional --purge-models.

$ localpilot self update

localpilot versions list | info | pin | compare | remove Model Versioning

Manages immutable model version records, pin protection against cleanup, side-by-side attribute comparison, and safe removal with reference-counted shared file preservation.

$ localpilot versions list

$ localpilot versions pin ver-12345 --reason "Approved baseline"

$ localpilot versions compare ver-1 ver-2

localpilot alias list | set | rollback | history Model Aliases

Maintains stable user- and API-facing pointers (default, writing, coding) with atomic version reassignment and instant rollback.

$ localpilot alias list

$ localpilot alias set coding ver-new

$ localpilot alias rollback coding

localpilot gateway start | status | stop Local Inference API

Runs a local authenticated OpenAI-compatible API gateway bound strictly to loopback (127.0.0.1:8080/v1) supporting /v1/models and streaming SSE /v1/chat/completions.

$ localpilot gateway start --daemon --port 8080

$ localpilot gateway status

localpilot keys | stats | connect Telemetry & Integration

Manages local API credentials, displays real-time request and token accounting (TPS, TTFT, latency), and generates guided configurations for OpenCode, VS Code Continue, and Cursor.

$ localpilot keys create "OpenCode" --app opencode

$ localpilot stats

$ localpilot connect opencode --write

localpilot connections list | test | disconnect Application Connections

Lists configured developer tool connections (OpenCode, Continue, Cursor), executes 5-stage diagnostic connectivity tests, and cleanly restores client configurations upon disconnect without destroying user modifications.

$ localpilot connections list

$ localpilot connections test conn_12345678

$ localpilot connections disconnect conn_12345678 --revoke-key

localpilot startup status | preview | enable | disable Automatic Gateway Startup

Manages unprivileged user-level background services on login (Linux systemd user services or macOS launchd LaunchAgents). Includes dry-run preview and never requires administrator/root privileges.

$ localpilot startup preview

$ localpilot startup enable

$ localpilot startup status

Dispatches sanitized lifecycle events (gateway startup, model loading, updates). Custom executable hooks execute under strict process isolation (argument array only, stripped environment, no shell, 5s timeout) with automated circuit breakers after 3 consecutive failures.

$ localpilot hooks list

$ localpilot hooks inspect hook_1234

$ localpilot hooks test hook_1234

Engineering Decisions & Guarantees

🗜️ Why GGUF & Q4_K_M?

GGUF is a single-file, mmap-capable binary format designed for high-performance CPU/GPU inference. Q4_K_M uses 4-bit block quantization with medium k-quant coverage, preserving 99%+ of 16-bit float perplexity while slashing memory consumption by ~65%.

🛡️ Process Boundary Respect

LocalPilot enforces non-destructive process supervision. If an Ollama or LM Studio daemon is detected on port 11434 or 1234, LocalPilot connects as an unprivileged client. It will never send SIGTERM, modify foreign config files, or alter third-party model stores.

🚫 Zero Synthetic Artifacts

Production code paths contain zero placeholder mock files. Model registration requires real HTTP/registry downloads, verified content lengths, and SHA-256 validation. A model is never marked TESTED_HERE until actual prompt inference passes.

🔄 Atomic Staging & Rollback

Updates never overwrite working model weights in place. New versions are staged in a temporary directory (~/.local/share/localpilot/backups/), verified with smoke inference, and atomically swapped only upon verified success.

Developer Setup & Contributing

LocalPilot is maintained on GitHub using modern Python tooling (uv / venv), full typing with Pydantic v2, and Pytest test coverage:

1. Clone the repository

$ git clone https://github.com/fakhruldeen/LocalPilot.git && cd LocalPilot

2. Create virtual environment & install dependencies

$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"

3. Run the automated test suite

$ pytest -v

Technical Architecture & CLI Reference