ModelDock

The lightweight, Python-first model manager for local AI models — the package manager for local LLMs.

ModelDock discovers, downloads, caches, verifies, and loads local LLMs through pluggable runtime adapters. It does not run inference itself; it orchestrates runtimes (starting with Ollama). No more manual ollama pull commands — just write md.load("llama3") and ModelDock handles the rest.

Features

• Python-first API — md.load("llama3") auto-installs if missing and returns a ready client.
• Searchable registry — browse models, categories, capabilities, and sizes without leaving Python.
• Bulk installation — md.install_category("coding") pulls recommended models at once.
• Smart caching — never re-download installed models; content-addressed offline cache.
• Extensible runtimes — Ollama ships first; LM Studio, llama.cpp, Jan AI, GPT4All, vLLM are drop-in adapters.
• Cross-platform — Windows, macOS, Linux via platformdirs.
• Zero-config, beginner-friendly — dynamic catalog from ollama.com with offline caching.

Quick Start

Prerequisites

• Python 3.9–3.12
• A local Ollama install (for the first runtime)

Installation

pip install modeldock
# with the Ollama backend helper (optional):
pip install modeldock[ollama]

Basic Usage

import modeldock as md

# Auto-installs if missing, then returns a ready-to-use client
client = md.load("llama3")

print(client.chat(model="llama3", messages=[{"role": "user", "content": "Hi!"}]))

Installation

From PyPI

pip install modeldock

From Source

git clone https://github.com/OpenAgentHQ/modeldock.git
cd modeldock
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,ollama]"

Usage

Discover and manage models

import modeldock as md

md.list()                       # browse the catalog
md.search("coding")             # search by name / capability / category
md.installed()                  # what's already local
md.info("qwen3")                # sizes, capabilities, variants
md.recommend(task="vision")     # guided pick

md.install("llama3")            # explicit download
md.install_category("coding")   # bulk install
md.update("llama3")             # pull newer tag
md.remove("llama3")             # uninstall
md.verify("llama3")             # integrity check

Command line

modeldock load llama3
modeldock install-category coding
modeldock list
modeldock search vision
modeldock cache status

See QUICKSTART.md for the full CLI/SDK reference.

Architecture

ModelDock follows Clean Architecture with SOLID principles. Dependencies point inward: cli → core → ports ← adapters. The domain and ports layers are pure (no I/O); concrete runtimes implement the RuntimePort protocol.

Interface:   modeldock/__init__.py (SDK)  +  modeldock/cli (Typer)
Application: modeldock/core/   (services, LifecycleOrchestrator, ModelManager)
Domain:      modeldock/domain/ (pure entities, no I/O)
Ports:       modeldock/ports/  (typing.Protocol interfaces)
Adapters:    modeldock/adapters/ (runtimes, registry, downloaders, cache, progress)
Common:      modeldock/common/ (config, logging, platform, http, errors)

Catalog Source

ModelDock scrapes ollama.com/library for a live model catalog, cached locally for 24 hours. Set catalog_source in config or MODELDOCK_CATALOG_SOURCE env var:

See Architecture.md for the full design contract.

Configuration

Config lives at ~/.config/modeldock/config.toml (Linux/macOS) or %APPDATA%\modeldock\config.toml (Windows). Env vars MODELDOCK_* override.

default_backend = "ollama"
auto_install    = true
log_level       = "INFO"
progress_style  = "rich"

Runtime server URLs

Runtimes that talk to a local server resolve their base URL in this order:

1. ollama_host / lmstudio_host in config.toml
2. MODELDOCK_OLLAMA_HOST / MODELDOCK_LMSTUDIO_HOST
3. The runtime's own convention — OLLAMA_HOST, LM_STUDIO_HOST
4. Auto-discovery — the first address that answers: localhost, 127.0.0.1, then host.docker.internal (so a container reaches a server on the host)
5. The documented default (http://localhost:11434, http://localhost:1234)

Discovery only runs when nothing is configured, so naming a host costs no probing. URLs are normalized: localhost:1234, a trailing slash, and the /v1-suffixed URL LM Studio's UI displays are all accepted.

llama.cpp GPU layers

llama-server binds one already-running process and has no API to report or change how many layers it offloaded to the GPU — that's a launch-time -ngl flag, not something a client can query or set afterwards. ModelDock lets you configure the value you use so every launch command it suggests (e.g. when the server isn't running yet) includes it:

1. llamacpp_gpu_layers in config.toml
2. MODELDOCK_LLAMACPP_GPU_LAYERS
3. LLAMA_ARG_N_GPU_LAYERS — llama-server's own env var for -ngl
4. Unset — suggested commands omit -ngl entirely

llamacpp_gpu_layers = 35  # or -1 to offload all layers

Supported Runtimes

Documentation

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, branch naming, coding standards, and the PR process.

You can claim an issue to work on by commenting /claim on it — a maintainer will assign it to you.

Support

• Issues: GitHub Issues
• Documentation: see the links above

See SUPPORT.md for more options.

Security

To report security vulnerabilities, see SECURITY.md. Do not open public issues for security problems.

Changelog

See CHANGELOG.md for a list of changes.

Author

ModelDock is created and maintained by Himanshu kumar (OpenAgentHQ).

License

ModelDock is licensed under the MIT License — see LICENSE for details.