feat(registry): honor registry mirrors for model pulls and backend do…

[doringeman]

Add MODEL_RUNNER_REGISTRY_MIRRORS support so model pulls and backend image downloads try configured mirrors before falling back to registry-1.docker.io.

To test:

MODEL_RUNNER_REGISTRY_MIRRORS=http://localhost:9999 MODEL_RUNNER_PORT=8080 make run LOCAL_LLAMA=1

MODEL_RUNNER_HOST=http://localhost:8080 docker model pull smollm2

Notice the logs:

time=2026-05-21T15:08:42.053+03:00 level=INFO msg="pulling model" model=smollm2
time=2026-05-21T15:08:42.053+03:00 level=INFO msg="starting model pull" component=model-manager reference=ai/smollm2:latest 
INFO[0041] trying next host
error="failed to do request: Head \"http://localhost:9999/v2/ai/smollm2/manifests/latest?ns=docker.io\": dial tcp 127.0.0.1:9999: connect: connection refused" host="localhost:9999"
time=2026-05-21T15:08:42.513+03:00 level=INFO msg="remote model digest" component=model-manager digest=sha256:354bf30d0aa3af413d2aa5ae4f23c66d78980072d1e07a5b0d776e9606a2f0b9
time=2026-05-21T15:08:43.089+03:00 level=INFO msg="model not found in local store, pulling from remote" component=model-manager reference=ai/smollm2:latest

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In server.Run you call envconfig.RegistryMirrors() twice (for ClientConfig and BackendsConfig); consider calling it once and reusing the slice to avoid redundant parsing and potential divergence if the env var changes between calls.
• In registryutil.RegistryHosts, it may be helpful to log which mirror ultimately succeeds (not just invalid ones) to make it easier to debug mirror ordering and behavior when pulls fall back to Docker Hub.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `server.Run` you call `envconfig.RegistryMirrors()` twice (for `ClientConfig` and `BackendsConfig`); consider calling it once and reusing the slice to avoid redundant parsing and potential divergence if the env var changes between calls.
- In `registryutil.RegistryHosts`, it may be helpful to log which mirror ultimately succeeds (not just invalid ones) to make it easier to debug mirror ordering and behavior when pulls fall back to Docker Hub.

## Individual Comments

### Comment 1
<location path="pkg/inference/backends/vllm/vllm.go" line_range="53" />
<code_context>
+	Config          *Config  // Linux-only: extra vllm args (nil = defaults)
+	LinuxBinaryPath string   // Linux: custom vllm binary path
+	MetalPythonPath string   // macOS ARM64: custom python path
+	RegistryMirrors []string // registry mirrors tried before registry-1.docker.io
 }

</code_context>
<issue_to_address>
**issue (bug_risk):** Registry mirrors are only wired through to the Metal backend, not the Linux vLLM backend

Options.RegistryMirrors is only passed to newMetal, so Linux vLLM flows won’t use the configured mirrors. If Linux should also respect these mirrors, thread them into newLinux (and its helpers). If mirrors are intentionally Metal-only, clarify or validate this in Options to avoid confusion about cross-platform behavior.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request implements support for registry mirrors by introducing the MODEL_RUNNER_REGISTRY_MIRRORS environment variable and propagating these settings through the OCI distribution client and various inference backends, including llama.cpp, vLLM, and diffusers. A new utility, registryutil.RegistryHosts, was added to handle the prioritization of mirrors for Docker Hub requests. Feedback was provided regarding an efficiency issue in pkg/internal/registryutil/mirrors.go, where instantiating a new http.Client within a closure could lead to resource exhaustion; using http.DefaultClient was suggested as a more efficient alternative.