Lotse

The one-command harbor pilot for local, private AI.

Lotse (German, [ˈloːtsə]) is the harbor pilot who comes aboard and guides a ship safely through tricky waters into port. This does the same for your first local-AI voyage.

Running your own AI assistant on your own machine — private, free, offline — is genuinely great. But getting there is brutal for a beginner: install Ollama, pick a model (VRAM? quantization? GGUF??), find the right Python (not too new!), create a venv, clone the app, install dependencies, run setup, start a server. Any one of those can fail with a wall of red text.

Lotse does all of it in one command — and when something is wrong, it tells you in plain language what and how to fix it, never just "crashed".

python -m lotse

It inspects your machine, picks a model that will actually run well on your hardware, checks every prerequisite, then sets up Ollama

• Odysseus (a self-hosted ChatGPT-style workspace) and starts it. You never see a config file.

---

What it looks like

On a machine with a 16 GB GPU (python -m lotse --dry-run):

  Lotse - your local-AI harbor pilot
  Getting a private AI assistant running on this machine.
  Nothing leaves your computer.

  This machine: windows, NVIDIA GeForce RTX 5060 Ti (16 GB graphics memory), 64 GB RAM.

==> Checking prerequisites
  [ok] Python 3.11-3.13: Found Python 3.12.10.
  [ok] git: Found at C:\Program Files\Git\cmd\git.EXE.
  [ok] Ollama: Found at ...\Ollama\ollama.EXE.
  [ok] Disk space: 762.8 GB free.

==> Choosing a model for your hardware
  Recommended model: Phi-4 14B
    Sharp reasoning for its size; great if your card has the room.
    Your GPU has about 15.9 GB of memory. Phi-4 14B is the strongest model that
    runs comfortably with room to spare for longer chats.
  Lighter/faster option: Llama 3.2 1B (~1 GB download)

And when a prerequisite is missing, you get a fix, not a stack trace:

  [!] Ollama: Ollama is not installed (or not on PATH).
        -> Install Ollama from https://ollama.com/download, then restart your terminal.

Quick start

# Nothing to install for Lotse itself - it is pure Python standard library.
python -m lotse              # guided setup
python -m lotse --dry-run    # show exactly what it would do, change nothing
python -m lotse --yes        # unattended (no prompts)
python -m lotse --dir ~/ai   # install Odysseus somewhere specific

Requirements to run Lotse: Python 3.9+ (standard library only). Requirements it will help you meet for the AI itself: Python 3.11–3.13, git, and Ollama.

How it works

Stage	Module	What it does
Detect	detect.py	OS, GPU + VRAM (nvidia-smi / Apple unified memory), RAM, a safe Python (3.11–3.13, avoiding 3.14), git, Ollama
Recommend	models.py	Picks the strongest model that fits your VRAM with headroom — no jargon. CPU fallback when there's no GPU
Check	preflight.py	Every prerequisite, each failure carrying a copy-pasteable fix
Install	steps.py + orchestrator.py	Pull model → clone Odysseus → venv → deps → setup → start, stopping at the first real error

Design rule: anything that touches the system is a thin, mockable wrapper; all the logic that's easy to get wrong (parsing nvidia-smi, ranking models, the Windows-vs-POSIX venv path) lives in pure functions with unit tests.

Tests

python -m pytest          # 69 tests, no GPU/network/Ollama required

Why "for everyone"

Local AI today is a power-user's toy because the on-ramp is a cliff. Lotse is the ramp. It does not add features to the AI — it removes the reasons a normal person gives up before the AI ever says hello.

Credits & license

Built to sit in front of Odysseus by pewdiepie-archdaemon and Ollama. Lotse is an independent companion tool, not affiliated with either.

MIT — see LICENSE.