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

importmodeldockasmd# Auto-installs if missing, then returns a ready-to-use clientclient=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

importmodeldockasmdmd.list() # browse the catalogmd.search("coding") # search by name / capability / categorymd.installed() # what's already localmd.info("qwen3") # sizes, capabilities, variantsmd.recommend(task="vision") # guided pickmd.install("llama3") # explicit downloadmd.install_category("coding") # bulk installmd.update("llama3") # pull newer tagmd.remove("llama3") # uninstallmd.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:

Value	Behavior
auto	Try dynamic, fallback to bundled (default)
ollama	Dynamic only — requires internet
bundled	Static catalog.json only — fully offline

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 = truelog_level = "INFO"progress_style = "rich"

Variable	Description	Default
MODELDOCK_LOG_LEVEL	DEBUG/INFO/WARNING/ERROR	ERROR
MODELDOCK_DEFAULT_BACKEND	Runtime backend	ollama
MODELDOCK_AUTO_INSTALL	Auto-download missing models	false
MODELDOCK_CACHE_DIR	Override cache location	platform default
MODELDOCK_OLLAMA_HOST	Ollama server base URL	auto-discovered
MODELDOCK_LMSTUDIO_HOST	LM Studio server base URL	auto-discovered
MODELDOCK_LLAMACPP_GPU_LAYERS	GPU layers to offload for llama.cpp	unset

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

Runtime	Status
Ollama	✅ Fully supported
LM Studio, llama.cpp, Jan AI, GPT4All, vLLM	Planned adapters

Documentation

File	Purpose
PROJECT.MD	Product vision, pain points, roadmap
Architecture.md	Design contract
AGENT.md	Agent/contributor rules + coding standards
QUICKSTART.md	30-second user start
Development.md	Build, test, CI, release setup
CONTEXT.md	Orientation hub
INSTRUCTIONS.md	How to work in this repo
RELEASE.md	Release process

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.