# ollama/ollama — codebase unpack

> Canonical page: https://codevetter.com/unpack/ollama

This is a deterministic Repo Unpack scan of ollama/ollama — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: 6383a0fa9cbf97494b847226e189f6e36b401a08 (2026-09-18)
- Last upstream commit: server: allow registry cross-host redirects among allowlisted hosts (#18533)
- Generated by codevetter 1.12.0 on 2026-09-22
- 1232 files scanned · 11.9 MB

## Languages

- Go: 774 files
- TypeScript: 104 files
- Markdown: 76 files
- C: 46 files
- JSON: 32 files
- Shell: 10 files
- YAML: 9 files
- C++: 4 files

## Repository structure

- app/ — 237 files
- mlxrunner/ — 141 files
- template/ — 104 files
- model/ — 102 files
- cmd/ — 96 files
- mlx/ — 88 files
- docs/ — 77 files
- server/ — 61 files

Probable source entrypoint: `cmd/bench` (inferred from the tree, not upstream docs)

## Source layout — app/

- app/auth/ — 1 file
- app/cmd/ — 22 files
- app/logrotate/ — 2 files
- app/tools/ — 11 files
- app/types/ — 3 files
- app/ui/ — 139 files
- app/webview/ — 4 files
- app/ollama.rc — 1 file

## Package

- go.mod: github.com/ollama/ollama — 0 declared dependencies

## Structural health signals

Average score 6.4/10 across 96 files; 48 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- 6383a0fa9cbf (2026-09-18) server: allow registry cross-host redirects among allowlisted hosts (#18533)
- d0c8cdb795d4 (2026-09-18) api: expose model thinking levels and defaults (#18473)
- 9a44d9d8de71 (2026-09-18) app: keep closed macOS windows from reopening on activation (#18518)
- 4f6f73983036 (2026-09-17) tests: fix metadata deletion test flake (#18493)
- 2c7316424653 (2026-09-17) nemotron_h: add MLX vision support (#17714)

## Overview

Ollama is a Go-based local LLM runner that packages models as OCI-style content-addressed blobs plus manifests under ~/.ollama/models, serves them through a Gin HTTP API on 127.0.0.1:11434, and delegates actual inference to per-model subprocesses — upstream llama-server for GGUF models and a bundled `ollama runner` MLX subprocess for safetensors models on Apple silicon. The same binary provides the end-user CLI (cobra), a Bubbletea TUI, and a desktop app (macOS/Windows webview + React/Vite chat UI backed by a sqlite store). Distinctively, it emulates OpenAI and Anthropic REST surfaces on top of its native /api/* routes via middleware translators, supports remote 'cloud' models hosted on ollama.com, and renders/parses chat formats in Go through per-model-family renderer and parser registries.

## System map

Single Go module (github.com/ollama/ollama) whose main binary is both the CLI client and the server. `ollama serve` starts a Gin HTTP server that owns a model Scheduler; inference is delegated to subprocesses (llama-server for GGUF, `ollama runner` for MLX/safetensors) spoken to over loopback HTTP. Model artifacts live as sha256 blobs + JSON manifests under OLLAMA_MODELS. Native code (vendored llama.cpp under llama/, MLX under mlx/) is built by CMake; the desktop app adds a webview shell and a React/Vite UI. Everything is configured through OLLAMA_* environment variables centralized in envconfig.
- Process entrypoint is main.go which calls cmd.NewCLI().ExecuteContext; all user-facing commands are cobra subcommands registered in NewCLI in cmd/cmd.go — [main.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/main.go) [cmd/cmd.go#L2385-L2600](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2385-L2600)
- The HTTP server is a Gin engine built by Server.GenerateRoutes, registering ~30 routes across /api/*, OpenAI-compatible /v1/*, and Anthropic /v1/messages — [server/routes.go#L1852-L1949](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1852-L1949)
- Inference scheduling is a channel-based Scheduler with pendingReqCh/finishedReqCh/expiredCh/unloadedCh, a loaded map of runnerRef keyed by model path, and a single in-flight load (activeLoading) — [server/sched.go#L61-L106](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L61-L106)
- GGUF inference runs in a separate llama-server subprocess spawned via exec.Command and driven over loopback HTTP through the llm.LlamaServer interface (Completion, Chat, Embedding, Tokenize, WaitUntilRunning, Close) — [llm/llama_server.go#L120-L160](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L120-L160) [llm/llama_server.go#L424](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L424) [llm/server.go#L58-L77](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L58-L77)
- Safetensors/MLX models take a different runner path: sched.load detects m.IsMLX() (Config.ModelFormat == "safetensors") and creates an mlxrunner.Client which re-execs the same binary as `ollama runner --model X --port N` — [server/sched.go#L530-L594](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L530-L594) [server/images.go#L93-L95](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L93-L95) [mlxrunner/client.go#L349](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/mlxrunner/client.go#L349) [cmd/cmd.go#L2569-L2576](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2569-L2576)
- Model storage is content-addressed: manifest.Path() -> OLLAMA_MODELS/manifests/<name>, BlobsPath() -> OLLAMA_MODELS/blobs/sha256-<hex>; manifests map model names to typed layers — [manifest/paths.go#L29-L72](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/manifest/paths.go#L29-L72) [server/model.go#L27-L97](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/model.go#L27-L97)
- Configuration is centralized in envconfig as OLLAMA_* variables (HOST, MODELS, KEEP_ALIVE, NUM_PARALLEL, MAX_LOADED_MODELS, MAX_QUEUE, ORIGINS, FLASH_ATTENTION, KV_CACHE_TYPE, NO_CLOUD, REMOTES, etc.) exposed via AsMap() — [envconfig/config.go#L20-L341](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L20-L341)
- The desktop app is a separate main package gated by `//go:build windows || darwin` in app/cmd/app/app.go, bundling a webview, sqlite-backed store (app/store/schema.sql), updater, and a React 19 + Vite + Tailwind UI under app/ui/app — [app/cmd/app/app.go#L1-L34](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/cmd/app/app.go#L1-L34) [app/store/schema.sql](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/store/schema.sql) [app/ui/app/package.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/ui/app/package.json)
- Full build is CMake-driven (cmake -B build .; cmake --build build) producing the Go binary plus native payload under build/lib/ollama; go build ./go run . serve works for Go-only iteration against an existing native payload — [AGENTS.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/AGENTS.md) [docs/development.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/docs/development.md) [CMakeLists.txt](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/CMakeLists.txt)
- Native engines are vendored/pinned: llama.cpp version in LLAMA_CPP_VERSION with llama/server sources, MLX pinned via MLX_VERSION and MLX_C_VERSION under mlx/, GPU backends selected via -DOLLAMA_LLAMA_BACKENDS=cuda_v12;cuda_v13;rocm_v7_1;rocm_v7_2;vulkan;cuda_jetpack5;cuda_jetpack6 — [docs/development.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/docs/development.md) [.github/workflows/test.yaml#L40-L49](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L40-L49) [LLAMA_CPP_VERSION](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/LLAMA_CPP_VERSION) [MLX_VERSION](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/MLX_VERSION)
- GPU/device discovery is performed by spawning helper binaries: `ollama gpu-discover` (hidden cobra cmd -> discover.RunNativeProbeCommand) and llama-server --list-devices probes in discover/llama_server.go — [cmd/cmd.go#L2581-L2590](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2581-L2590) [discover/native_probe.go#L86](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/discover/native_probe.go#L86) [discover/llama_server.go#L143](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/discover/llama_server.go#L143) [discover/runner.go#L36-L80](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/discover/runner.go#L36-L80)
- The CLI talks to the server through api.Client (api/client.go) whose methods map 1:1 to the REST API and which reads OLLAMA_HOST via ClientFromEnvironment — [api/client.go#L1-L79](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/client.go#L1-L79)

## Feature catalog

User-facing surface = CLI subcommands + REST endpoints + OpenAI/Anthropic compat shims + a desktop chat app. Features cover the full model lifecycle (pull/create/push/copy/show/list/ps/delete), inference (generate/chat/embed with streaming NDJSON, thinking, tools, vision/audio, structured output, logprobs), cloud remote inference on ollama.com, experimental web search/fetch, and Codex Desktop integration via a loopback proxy.
- CLI commands: create, show, run, stop, serve (alias start), pull, push, signin/login, signout/logout, list, ps, cp, rm; hidden commands `runner` (MLX runner entrypoint) and `gpu-discover` — [cmd/cmd.go#L2393-L2595](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2393-L2595)
- Native API endpoints: /api/generate, /api/chat, /api/embed, /api/embeddings, /api/pull, /api/push, /api/tags (GET+HEAD), /api/show, /api/delete, /api/create, /api/blobs/:digest (POST+HEAD), /api/copy, /api/ps, /api/me, /api/signout, /api/version, /api/status — [server/routes.go#L1892-L1930](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1892-L1930)
- OpenAI-compatible endpoints /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/models(+/:model), /v1/responses(+ /compact), /v1/audio/transcriptions are middleware translators over the native handlers — [server/routes.go#L1932-L1943](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1932-L1943) [middleware/openai.go#L27-L80](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/openai.go#L27-L80) [openai/openai.go#L1-L30](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/openai/openai.go#L1-L30)
- Anthropic compatibility is provided by POST /v1/messages -> middleware.AnthropicMessagesMiddleware -> ChatHandler — [server/routes.go#L1945-L1946](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1945-L1946) [middleware/anthropic.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/anthropic.go) [anthropic/anthropic.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/anthropic/anthropic.go)
- `ollama create` supports two paths: classic Modelfile+API (parser.ParseFile -> CreateRequest -> blob upload -> /api/create) and in-process safetensors import with --quantize/--draft-quantize/--force when the server is local (OLLAMA_CREATE_REMOTE forces remote) — [cmd/cmd.go#L220-L315](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L220-L315) [cmd/cmd.go#L317-L400](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L317-L400) [parser/parser.go#L56-L120](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/parser/parser.go#L56-L120) [create/create.go#L22-L100](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/create/create.go#L22-L100)
- Chat features include thinking control (think bool or level; --think/--hidethinking flags), tool calling via api.Tools parsed by model parsers, vision/audio inputs (ImageData, MediaKind), and shift/truncate context management options — [api/types.go#L104-L120](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/types.go#L104-L120) [cmd/cmd.go#L830-L855](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L830-L855) [llm/server.go#L156-L228](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L156-L228) [model/parsers/parsers.go#L12-L24](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/parsers.go#L12-L24)
- Structured output: GenerateRequest.Format accepts a JSON schema which is passed to llama-server's json_schema field; a built-in BNF grammarJSON exists for generic JSON mode — [api/types.go#L89-L91](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/types.go#L89-L91) [llm/llama_server.go#L8-L10](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L8-L10) [llm/llama_server.go#L52-L73](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L52-L73)
- Cloud/remote models: models whose Config has RemoteHost+RemoteModel are proxied by ChatHandler to remoteURL via api.NewClient, gated by envconfig.Remotes() allowlist and OLLAMA_NO_CLOUD; :cloud model refs take cloudPassthroughMiddleware on /v1 routes (inferred) — [server/routes.go#L2555-L2621](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2555-L2621) [server/routes.go#L1935-L1946](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1935-L1946) [envconfig/config.go#L166-L177](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L166-L177) [internal/cloud/policy.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/internal/cloud/policy.go)
- Experimental endpoints: POST /api/experimental/web_search, /api/experimental/web_fetch, GET /api/experimental/model-recommendations served from a stale-while-revalidate modelCaches.recommendations — [server/routes.go#L1921-L1923](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1921-L1923) [server/routes.go#L1951-L1967](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1951-L1967) [middleware/web_search.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/web_search.go)
- A loopback-only Codex Desktop reverse proxy is mounted at /api/codex/* (proxy.CodexDesktopPathPrefix) to route between native Ollama models and Codex upstreams, with request logging via writeActivity — [server/routes.go#L1898-L1900](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1898-L1900) [internal/proxy/codex_desktop.go#L28-L30](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/internal/proxy/codex_desktop.go#L28-L30) [internal/proxy/codex_desktop.go#L157-L163](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/internal/proxy/codex_desktop.go#L157-L163) [internal/proxy/codex_desktop.go#L645-L657](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/internal/proxy/codex_desktop.go#L645-L657)
- Model auth uses an ed25519 keypair at ~/.ollama/id_ed25519 generated on serve start (initializeKeypair); registry challenge-response tokens are obtained via signed nonce requests (getAuthorizationToken) — [cmd/cmd.go#L2101-L2163](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2101-L2163) [server/auth.go#L22-L100](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/auth.go#L22-L100)
- Interactive UX: bare `ollama` launches a Bubbletea TUI (runInteractiveTUI + welcome flow via cmd/launch + cmd/tui); `ollama run` without prompt enters readline-based interactive session; selectors/sign-in/upgrade prompts are injected as launch.Default* hooks — [cmd/cmd.go#L62-L99](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L62-L99) [cmd/cmd.go#L2400-L2414](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2400-L2414) [cmd/interactive.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/interactive.go)
- Separate `bench` main package under cmd/bench provides a benchmarking CLI hitting the API (used by CI bench step) — [cmd/bench/bench.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/bench/bench.go) [.github/workflows/test.yaml#L451-L455](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L451-L455)

## Data flow

Requests enter via Gin handlers -> model resolution (manifest -> Model struct) -> option merge (defaults < generation defaults < model < request) -> Scheduler -> runner subprocess over loopback HTTP -> streamed tokens parsed back into API responses. Model artifacts flow registry -> blob downloads -> manifest write; create flows Modelfile/safetensors dir -> layer blobs -> manifest. Chat text flows messages -> Go renderer or llama-server chat template -> prompt -> token stream -> Parser.Add splits content/thinking/tool calls -> NDJSON stream.
- Option precedence is layered in modelOptions: api.DefaultOptions -> model.GenerationDefaults (parsed from GGUF metadata) -> model.Options (Modelfile params) -> request options, with embedding models getting a NumBatch=2048 default capped by context — [server/routes.go#L125-L172](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L125-L172) [server/images.go#L110-L135](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L110-L135) [llm/llama_server.go#L90-L104](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L90-L104)
- Chat path in ChatHandler: ShouldBindJSON -> parseAndValidateModelRef -> getExistingName -> GetModel -> (unload shortcut for keep_alive=0) -> scheduleRunner -> renderer/parser selection -> llm runner Chat/Completion -> NDJSON stream to client — [server/routes.go#L2465-L2540](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2465-L2540) [server/routes.go#L3016](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L3016)
- GetModel resolves a name through manifest.ParseNamedManifest -> config blob decode (ConfigV2) -> layer iteration, grouping split GGUF shards via groupManifestSplitGGUFLayers; parseFromModel auto-pulls when the manifest is missing — [server/model.go#L27-L97](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/model.go#L27-L97) [server/images.go#L656](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L656)
- Prompt rendering branches: models with a Go renderer name go through renderers.RenderWithRenderer; others use template.Template (embedded .gotmpl set indexed by index.json) or llama-server's native chat_template via /v1/chat/completions — [model/renderers/renderer.go#L40-L60](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/renderers/renderer.go#L40-L60) [template/template.go#L1-L40](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/template.go#L1-L40) [llm/llama_server.go#L3-L13](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L3-L13) [server/images.go#L362-L432](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L362-L432)
- Output parsing: streamed runner tokens are fed to Parser.Add which returns (content, thinking, toolCalls); PreservedTokens tells llama-server which grammar tokens must survive detokenization — [model/parsers/parsers.go#L12-L24](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/parsers.go#L12-L24) [llm/server.go#L197-L208](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L197-L208)
- Pull flow: PullHandler -> PullModel -> registry layer resolution -> blobDownload.Run with chunked resumable parts -> sha256 verification -> manifest write; progress is fanned out as api.ProgressResponse over a channel to streamResponse — [server/routes.go#L1135-L1193](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1135-L1193) [server/images.go#L1002](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L1002) [server/download.go#L187-L476](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/download.go#L187-L476)
- Blob writes are content-addressed: CreateBlobHandler accepts POST /api/blobs/:digest and HeadBlobHandler probes existence; digest validity enforced by manifest.ValidateDigest regex sha256[:-][64 hex] — [server/routes.go#L1715-L1852](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1715-L1852) [manifest/paths.go#L15-L27](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/manifest/paths.go#L15-L27)
- Runner placement: scheduler loads GGUF metadata (llm.LoadModel), predicts VRAM via llm.PredictServerVRAM, selects GPUs via selectLlamaServerPlacement honoring OLLAMA_SCHED_SPREAD and OLLAMA_GPU_OVERHEAD, then evicts loaded runners if predicted footprint exceeds 80% of free memory — [server/sched.go#L528-L575](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L528-L575) [llm/llama_server.go#L2698](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L2698)
- llama-server subprocesses receive model path, ports, -ngl/-t only when explicitly set (otherwise auto-detect), media marker rewriting ([img-N]) for vision, and report memory back via parsed log lines into runner's vramByDevice/systemFreeAtLoad — [llm/llama_server.go#L400-L440](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L400-L440) [llm/llama_server.go#L120-L160](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L120-L160)
- Desktop app persists chats/settings in sqlite (mattn/go-sqlite3) via app/store with a frozen v2 schema (schema.sql) plus migrations; the React UI talks to the same Ollama HTTP API — [app/store/schema.sql](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/store/schema.sql) [app/store/database.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/store/database.go) [app/ui/app/package.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/ui/app/package.json) [go.mod#L12](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/go.mod#L12)
- Inference request logging is optional and bounded: withInferenceRequestLogging wraps /api/generate, /api/chat, and the /v1 inference routes, gated by OLLAMA_DEBUG_LOG_REQUESTS — [server/routes.go#L1927-L1946](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1927-L1946) [server/inference_request_log.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/inference_request_log.go) [envconfig/config.go#L220](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L220)
- Context management: num_ctx defaults come from OLLAMA_CONTEXT_LENGTH or a VRAM-tier auto default (numCtxAuto), clamped to model train context; `shift` enables sliding-window context shift except for deepseek2 family; `truncate` drops history instead of erroring — [server/sched.go#L134-L172](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L134-L172) [server/sched.go#L174-L200](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L174-L200) [envconfig/config.go#L230](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L230) [envconfig/config.go#L338](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L338)

## Behavior traces

Three canonical flows: (1) serve startup: main -> cobra serve -> initializeKeypair -> net.Listen -> server.Serve -> blob prune -> GenerateRoutes -> InitScheduler.Run; (2) `ollama run X prompt`: CLI heartbeat/pull -> api.Client.Chat -> ChatHandler -> GetModel -> getRunner -> load -> llama-server subprocess -> streamed parse -> NDJSON; (3) pull: PullHandler -> PullModel -> blob downloads -> manifest write. Safetensors models diverge at sched.load into the mlxrunner subprocess.
- Startup order: main() -> NewCLI() -> serveCmd -> RunServer -> initializeKeypair (ed25519 at ~/.ollama) -> net.Listen(envconfig.Host) -> server.Serve(ln) — [main.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/main.go) [cmd/cmd.go#L2101-L2117](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2101-L2117) [cmd/cmd.go#L2119-L2163](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2119-L2163)
- server.Serve sequence: slog logger init -> log cloud-disabled status -> llm.PruneSplitModelDirs on blobs dir -> fixBlobs -> PruneLayers + manifest.PruneDirectory (unless OLLAMA_NOPRUNE) -> GenerateRoutes -> InitScheduler -> sched.Run goroutines -> http.Serve — [server/routes.go#L1969-L2031](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1969-L2031) [server/sched.go#L91-L106](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L91-L106) [server/sched.go#L219-L220](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L219-L220)
- CLI run flow: RunHandler parses --think/--keepalive/--format flags -> api.ClientFromEnvironment -> showOrPullModel (pulls if absent) -> inferThinkingOption -> isEmbeddingModel branch -> generateChat/generateInteractive -> client.Chat -> POST /api/chat — [cmd/cmd.go#L814-L953](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L814-L953) [api/client.go#L74-L79](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/client.go#L74-L79)
- Server chat flow: ChatHandler binds JSON -> parseAndValidateModelRef -> cloud refs proxied via proxyCloudJSONRequest -> GetModel -> keep_alive=0 unloads via sched.expireRunner -> remote models proxied to RemoteHost -> otherwise modelOptions + scheduleRunner — [server/routes.go#L2465-L2553](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2465-L2553) [server/routes.go#L2555-L2621](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2555-L2621) [server/routes.go#L205-L253](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L205-L253)
- Scheduling flow: getRunner builds LlmRequest -> loaded-map fast path via schedulerModelKey (modelPaths joined with NUL, or digest:/name: fallback) -> else enqueue pendingReqCh (ErrMaxQueue when full) -> scheduler picks GPUs -> load() spawns runner -> useLoadedRunner — [server/sched.go#L108-L132](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L108-L132) [server/sched.go#L174-L216](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L174-L216) [server/sched.go#L520-L632](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L520-L632)
- GGUF runner launch: sched.load -> llm.LoadModel (gguf.ReadModel metadata) -> PredictServerVRAM -> selectLlamaServerPlacement -> newServerFn = llm.NewLlamaServer -> NewLlamaServerRunner -> startLlamaServer -> exec.Command(llama-server, params) -> WaitUntilRunning polls /health — [server/sched.go#L528-L600](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L528-L600) [llm/server.go#L93-L111](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L93-L111) [llm/llama_server.go#L348](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L348) [llm/llama_server.go#L424](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L424) [llm/llama_server.go#L851](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L851)
- MLX runner launch: sched.load -> m.IsMLX() -> mlxrunner.NewClient(modelName, numCtx) -> exec.Command(self, "runner", --model, --port) -> hidden cobra `runner` cmd -> mlxrunner.Execute -> HTTP server inside subprocess — [server/sched.go#L591-L594](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L591-L594) [mlxrunner/client.go#L349](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/mlxrunner/client.go#L349) [cmd/cmd.go#L2569-L2576](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2569-L2576)
- Pull trace: PullHandler binds api.PullRequest -> parseNormalizePullModelRef (normalizes :cloud) -> PullModel in goroutine -> per-layer blobDownload (chunked parts with backoff) -> manifest write -> progress channel -> streamResponse emits api.ProgressResponse NDJSON — [server/routes.go#L1135-L1193](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1135-L1193) [server/images.go#L1002](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L1002) [server/download.go#L187-L333](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/download.go#L187-L333)
- Create trace (Modelfile): CreateHandler -> readCreateModelfile -> parser.ParseFile -> reject adapter/typical_p -> modelfile.CreateRequest -> createBlob uploads per file (or sharedBlobStore local shortcut) -> client.Create -> /api/create -> server assembles layers + manifest — [cmd/cmd.go#L220-L241](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L220-L241) [cmd/cmd.go#L317-L400](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L317-L400) [parser/parser.go#L56-L120](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/parser/parser.go#L56-L120) [server/routes.go#L1917](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1917)
- Unload/keep-alive: empty chat request with keep_alive=0 triggers sched.expireRunner and returns done_reason=unload without inference; runners expire via expiredCh after sessionDuration (OLLAMA_KEEP_ALIVE default 5m) — [server/routes.go#L2541-L2553](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2541-L2553) [server/sched.go#L61-L82](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L61-L82) [envconfig/config.go#L126-L144](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L126-L144)
- OOM resilience: on llm.IsOutOfMemory during Load, scheduler reduces automatically-derived num_ctx/num_batch once (oomRetryAttempted) and retries; evict-all-and-retry is guarded against infinite loops — [server/sched.go#L39-L42](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L39-L42) [server/sched.go#L632-L659](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L632-L659)

## Testing signals

Testing is Go-test-first with heavy coverage in server/, model/parsers, model/renderers, middleware, mlxrunner, create, envconfig; testify is the assertion library. integration/ holds end-to-end suites gated on a live server/registry; CI runs go test -count=1 ./... plus a -race job, golangci-lint, patch-apply checks, vitest for the React app, and a benchmark pass.
- CI test.yaml runs `go test -count=1 -bench=. -benchtime=1x ./...` on PRs and a separate `go test -race -count=1 ./...` race job — [.github/workflows/test.yaml#L451-L455](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L451-L455) [.github/workflows/test.yaml#L500-L501](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L500-L501)
- CI includes golangci-lint (golangci-lint-action@v9), go_mod_tidy and go_license checks, plus a patches job that verifies llama/server patches apply cleanly under CMake — [.github/workflows/test.yaml#L62-L80](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L62-L80) [.github/workflows/test.yaml#L370-L394](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L370-L394) [.github/workflows/test.yaml#L461](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L461)
- The desktop app is tested with `go test -tags updater_live ./app/...` and the React UI via `npm ci && npm test` (vitest) plus npm run build; Storybook config also present (build-storybook script) — [.github/workflows/test.yaml#L427-L434](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L427-L434) [.github/workflows/test.yaml#L457-L459](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L457-L459) [app/ui/app/package.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/ui/app/package.json)
- server/ has ~30 *_test.go files including routes_*_test.go per endpoint family, a fuzz test (create_fuzz_test.go), and sched_test.go for scheduler logic — [server/create_fuzz_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/create_fuzz_test.go) [server/routes_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes_test.go) [server/sched_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched_test.go)
- model/parsers and model/renderers have per-family test files plus reference-test files (nemotron*_reference_test.go) and shared testhelpers_test.go — [model/parsers/parsers_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/parsers_test.go) [model/parsers/testhelpers_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/testhelpers_test.go) [model/renderers/renderer_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/renderers/renderer_test.go)
- integration/ contains end-to-end tests (api_test, concurrency_test, max_queue_test, vision/audio tests, reg_* group files) that require a running server and real model pulls — documented in integration/README.md — [integration/README.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/integration/README.md) [integration/api_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/integration/api_test.go) [integration/max_queue_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/integration/max_queue_test.go)
- Test isolation uses OLLAMA_MODELS/home overrides: many packages ship test_home_test.go helpers to redirect model storage into temp dirs (inferred) — [envconfig/test_home_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/test_home_test.go) [server/test_home_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/test_home_test.go) [middleware/test_home_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/test_home_test.go)
- template/ has a golden-file style test driven by embedded index.json + per-model .gotmpl/.json pairs (template_test.go) — [template/template_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/template_test.go) [template/template.go#L22-L40](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/template.go#L22-L40)
- api/ tests include types_typescript_test.go which cross-checks Go API types against generated TypeScript (typescriptify dep in go.mod) — [api/types_typescript_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/types_typescript_test.go) [go.mod#L29](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/go.mod#L29)
- Coverage gaps: Objective-C/macOS glue (app/cmd/app/*.m, discover/gpu_info_darwin.m) and the codex_desktop_autoreview/proxy hot paths have tests but the darwin app lifecycle is largely untestable in CI (build-tagged windows||darwin) (inferred) — [app/cmd/app/app.go#L1](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/cmd/app/app.go#L1) [app/cmd/app/codex_app_darwin.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/cmd/app/codex_app_darwin.go) [discover/gpu_info_darwin.m](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/discover/gpu_info_darwin.m)

## Risk map

Main risks: the API has no request authentication by default and can be bound to non-loopback hosts via OLLAMA_HOST; the server spawns subprocesses (llama-server, self runner, gpu probes) with model-derived arguments; startup blob pruning deletes on-disk data; registry push/pull signs with a local private key; and several middleware paths decompress/transform untrusted request bodies. Scheduler and runner state is intricate (eviction, OOM retry, panic on model mismatch during load).
- The REST API is unauthenticated; OLLAMA_HOST can bind it to 0.0.0.0 and OLLAMA_ORIGINS CORS allows wildcards/browser extensions, so any reachable origin can pull/delete/run models unless the operator restricts it (inferred) — [server/routes.go#L1858-L1890](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1858-L1890) [envconfig/config.go#L85-L111](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L85-L111) [envconfig/config.go#L324](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L324)
- Subprocess attack surface: llama-server is exec'd with flags assembled from request/model options (num_ctx, -ngl, -t, chat templates); the runner binary path and env are constructed in startLlamaServer/SetupLlamaServerCommandEnv — [llm/llama_server.go#L400-L435](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L400-L435) [llm/llama_server.go#L424](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L424)
- Startup performs destructive maintenance: PruneLayers, manifest.PruneDirectory and fixBlobs delete blobs/manifests under OLLAMA_MODELS; guarded only by OLLAMA_NOPRUNE and a 1h grace period for fresh blobs — [server/routes.go#L1979-L2004](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1979-L2004) [server/images.go#L37-L39](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L37-L39) [manifest/paths.go#L74-L106](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/manifest/paths.go#L74-L106)
- Private signing key ~/.ollama/id_ed25519 (0600) is generated on first serve and used by auth.Sign for registry token exchange; realm host is checked against original host to avoid token leakage cross-origin — [cmd/cmd.go#L2119-L2163](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2119-L2163) [server/auth.go#L53-L62](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/auth.go#L53-L62)
- --insecure / registryOptions.Insecure permits plain-HTTP registry traffic (errInsecureProtocol exists but can be bypassed by request flag) — [server/images.go#L41-L61](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L41-L61) [cmd/cmd.go#L2455](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2455)
- Request-body decompression is capped at 20MB (maxDecompressedBodySize) in the OpenAI middleware — a decompression-bomb guard; other endpoints bind JSON directly via gin ShouldBindJSON without explicit size limits — [middleware/openai.go#L24-L25](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/openai.go#L24-L25) [server/routes.go#L2473](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2473)
- Scheduler contains a deliberate panic when the active load's ModelPath differs from the evicted-retry request — a crash-on-invariant-violation that takes down the whole server — [server/sched.go#L603-L611](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L603-L611)
- Secret hygiene in logs: filteredEnv redacts env values containing API/KEY/TOKEN/SECRET/PASSWORD/CREDENTIAL/AUTH before logging subprocess env, but only CUDA_/ROCR_/ROCM_/HIP_/HSA_/GGML_/PATH/LD_LIBRARY_PATH/DYLD_LIBRARY_PATH keys are logged at all — [llm/server.go#L21-L56](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L21-L56)
- Codex desktop proxy restricts to loopback requests (isLoopbackRequest) and websocket upgrades are special-cased; misconfiguration here would expose upstream proxying on the shared listener — [internal/proxy/codex_desktop.go#L645-L657](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/internal/proxy/codex_desktop.go#L645-L657) [server/routes.go#L1898-L1900](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1898-L1900)
- Runner stream parsing bounds single response lines at 8MB (llamaServerStreamMaxBufferSize); unbounded growth in a misbehaving subprocess is otherwise handled only via HasExited/ping timeouts — [llm/server.go#L150-L154](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L150-L154)
- Legacy/removed features linger as explicit errors: LoRA adapters rejected (errAdaptersUnsupported), typical_p rejected, `useClient2` experiment warns-and-continues; dead flags like --experimental are hidden no-ops — [cmd/cmd.go#L292-L296](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L292-L296) [cmd/cmd.go#L2431-L2433](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2431-L2433) [server/routes.go#L93](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L93) [server/routes.go#L2014-L2016](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L2014-L2016)
- Blast radius: a single Scheduler serializes all model loads (activeLoading) so a stuck subprocess load stalls every inference request; queue overflow surfaces as ErrMaxQueue (OLLAMA_MAX_QUEUE default 512) — [server/sched.go#L61-L89](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L61-L89) [envconfig/config.go#L281](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L281)

## Extension points

Deliberate plug-in surfaces: per-model-family Parser and Renderer registries (name-keyed constructors with a switch fallback), embedded named chat templates, the llm.LlamaServer runner interface, cobra command table, launch.Default* UI hooks, middleware translators for new API dialects, envconfig's AsMap registry, and the create/ import pipeline stages.
- New output parsers plug in via parsers.Register(name, constructor) or a case in ParserForName's switch; Parser interface = Init/Add/PreservedTokens/HasToolSupport/HasThinkingSupport — [model/parsers/parsers.go#L12-L107](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/parsers.go#L12-L107)
- New prompt renderers plug in via renderers.Register or rendererForName switch; Renderer interface = Thinking/Render/LeadingBOS; RenderImgTags global toggles [img] tag emission — [model/renderers/renderer.go#L10-L60](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/renderers/renderer.go#L10-L60) [server/routes.go#L116-L118](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L116-L118)
- Named Go templates are added as .gotmpl+.json pairs embedded via go:embed and indexed in template/index.json; template.Named resolves by GGUF chat_template name for autodetection — [template/template.go#L22-L40](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/template.go#L22-L40) [server/model.go#L99-L138](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/model.go#L99-L138) [template/index.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/index.json)
- New inference backends implement llm.LlamaServer (Completion/Chat/Embedding/Tokenize/WaitUntilRunning/Close/...) and get wired through Scheduler.newServerFn or the IsMLX branch (mlxrunner.Client) — [llm/server.go#L58-L77](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/server.go#L58-L77) [server/sched.go#L77-L104](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L77-L104) [mlxrunner/client.go#L32-L40](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/mlxrunner/client.go#L32-L40)
- New API dialects slot into GenerateRoutes as gin middleware translators in middleware/ (ChatMiddleware, CompletionsMiddleware, ResponsesMiddleware, AnthropicMessagesMiddleware, TranscriptionMiddleware) wrapping the core handlers — [server/routes.go#L1935-L1946](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1935-L1946) [middleware/openai.go#L27-L80](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/openai.go#L27-L80) [middleware/anthropic.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/middleware/anthropic.go)
- New CLI commands register in NewCLI's command table; hidden/internal commands (runner, gpu-discover) show the pattern for plumbing sub-binaries through the same binary — [cmd/cmd.go#L2393-L2600](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2393-L2600) [cmd/cmd.go#L2569-L2590](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L2569-L2590)
- Interactive UI is swappable via launch.Default* function hooks (SingleSelector, MultiSelector, SignIn, Upgrade, ConfirmPrompt, Spinner) — cmd/cmd.go's init() replaces them with Bubbletea TUI implementations — [cmd/cmd.go#L62-L99](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L62-L99)
- New environment settings register in envconfig: typed accessors (Bool/Uint/String/BoolWithDefault) plus an entry in AsMap() so `ollama serve` logs and help list them — [envconfig/config.go#L177-L290](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L177-L290) [envconfig/config.go#L313-L341](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L313-L341)
- GPU backends are build-time extensions: OLLAMA_LLAMA_BACKENDS selects cuda_v12/cuda_v13/rocm_v7_1/rocm_v7_2/vulkan/jetpack variants; runtime discovery globs lib/ollama/*/ggml-* dirs — [docs/development.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/docs/development.md) [discover/runner.go#L45-L58](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/discover/runner.go#L45-L58)
- Safetensors import is a staged pipeline in create/ (classify -> transform -> prequant -> quantize -> writer -> manifest) with per-architecture files (gemma4.go, qwen35.go, cohere2moe.go, glimmer.go, nemotron_h.go, laguna.go) — new architectures add a file + classification entry — [create/create.go#L73-L100](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/create/create.go#L73-L100) [create/classify.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/create/classify.go) [create/pipeline.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/create/pipeline.go) [create/transform.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/create/transform.go)
- Model capabilities are declared via model.Capability flags (completion, tools, insert, vision, audio, embedding, thinking, image) checked through Model.CheckCapabilities, gating handler behavior per request — [server/images.go#L41-L52](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L41-L52) [server/images.go#L137-L140](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L137-L140) [server/sched.go#L179-L182](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L179-L182)

## Contributor handoff

Start with AGENTS.md and docs/development.md. Build Go-only via `go build .`/`go run . serve`; full builds need CMake (native payload under build/lib/ollama). Tests: `go test ./...` (race: `go test -race ./...`), vitest under app/ui/app, integration/ needs a live server. Read cmd/cmd.go, server/routes.go, server/sched.go, llm/llama_server.go first. Traps: dual runner paths (GGUF subprocess vs MLX self-runner), removed features that still error loudly, scheduler panics, and env-var-driven behavior.
- Authoritative onboarding docs: AGENTS.md (build commands), docs/development.md (prereqs, GPU backends, platform notes), docs/api.md (REST reference) — [AGENTS.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/AGENTS.md) [docs/development.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/docs/development.md) [docs/api.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/docs/api.md)
- Read-first files for server changes: cmd/cmd.go (CLI+RunServer), server/routes.go (GenerateRoutes + handlers), server/sched.go (Scheduler lifecycle), server/images.go (Model + pull/create/prune), llm/llama_server.go (runner subprocess) — [cmd/cmd.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go) [server/routes.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go) [server/sched.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go) [server/images.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go) [llm/llama_server.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go)
- Shared types live in api/types.go and are the contract between CLI client, server handlers, and the generated TypeScript (checked by api/types_typescript_test.go) — change them carefully — [api/types.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/types.go) [api/client.go#L1-L14](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/client.go#L1-L14) [api/types_typescript_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/api/types_typescript_test.go)
- Model support additions typically touch four places: model/parsers (output), model/renderers (prompt), template/ (named .gotmpl), and server/images.go capability/template selection — plus create/ for safetensors architectures (inferred) — [model/parsers/parsers.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/parsers/parsers.go) [model/renderers/renderer.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/model/renderers/renderer.go) [template/index.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/template/index.json) [server/images.go#L362-L432](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/images.go#L362-L432)
- Safe edit boundaries: middleware/ translators and model/{parsers,renderers} are well-isolated and heavily tested; sched.go and llm/llama_server.go are high-blast-radius (concurrency + subprocess lifecycle) — add tests in the same package's *_test.go (inferred) — [server/sched.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go) [llm/llama_server.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go) [server/sched_test.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched_test.go)
- Known traps: (a) LoRA adapters and typical_p are removed and error on use; (b) NumGPU==-1 means auto, 0 means CPU-only — don't collapse; (c) num_ctx auto-detection is VRAM-tiered (numCtxAuto flag) and OOM retry reduces it once; (d) scheduler model keys join shard paths with NUL — [cmd/cmd.go#L292-L296](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/cmd.go#L292-L296) [llm/llama_server.go#L404-L411](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llama_server.go#L404-L411) [server/sched.go#L43-L49](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L43-L49) [server/sched.go#L111-L120](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/sched.go#L111-L120)
- Environment knobs for debugging: OLLAMA_DEBUG=1 (log level), OLLAMA_DEBUG_LOG_REQUESTS (request replay logs to temp dir), OLLAMA_LOAD_TIMEOUT (stall detection), OLLAMA_NOPRUNE (disable startup deletion), OLLAMA_HOST/OLLAMA_MODELS (paths/bind) — [envconfig/config.go#L201-L240](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L201-L240) [envconfig/config.go#L315-L340](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/envconfig/config.go#L315-L340) [server/inference_request_log.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/inference_request_log.go)
- Test commands: `go test -count=1 ./...` locally (some packages need CGO/native payload), `go test -race ./...` mirrors CI race job, `npm test`/`npm run build` under app/ui/app; integration tests are opt-in (need pulled models + running server) — [.github/workflows/test.yaml#L451-L501](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L451-L501) [integration/README.md](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/integration/README.md) [app/ui/app/package.json](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/app/ui/app/package.json)
- Platform-conditional code uses file-suffix build tags (llm_linux.go, llm_darwin.go, llm_windows.go, editor_unix.go, start_darwin.go) — edit the right variant and keep signatures identical across OSes — [llm/llm_linux.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llm_linux.go) [llm/llm_darwin.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/llm/llm_darwin.go) [cmd/editor_unix.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/editor_unix.go) [cmd/start_darwin.go](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/cmd/start_darwin.go)
- Gin runs in DebugMode by default (mode var = gin.DebugMode with a defensive switch); don't rely on release-mode assumptions in handlers — [server/routes.go#L95-L114](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L95-L114)
- The repo mixes vendored native code (llama/ llama.cpp fork, mlx/) with Go; changes under llama/server or cmake/ trigger the `patches` CI job verifying patches apply — avoid touching unless intentional — [.github/workflows/test.yaml#L35-L80](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/.github/workflows/test.yaml#L35-L80) [LLAMA_CPP_VERSION](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/LLAMA_CPP_VERSION) [MLX_VERSION](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/MLX_VERSION)
- Progress reporting convention: long operations (pull/create/push) emit api.ProgressResponse structs over a channel consumed by streamResponse — new streaming endpoints should reuse that pattern — [server/routes.go#L1161-L1193](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/routes.go#L1161-L1193) [server/download.go#L446-L476](https://github.com/ollama/ollama/blob/6383a0fa9cbf97494b847226e189f6e36b401a08/server/download.go#L446-L476)

Source repository: https://github.com/ollama/ollama
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/ollama.json

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)