A setting to turn off the models.dev catalog download (offline and strict-network use)

Open Beginner friendly
#4,714 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@3431481073 is already working on this.

Since Oct 29, 2026.

  • #4768 by @3431481073 — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
docker, go
Domain
backend

Research direction

Start in pkg/modelsdev/store.go: read fetchFromAPI, loadDatabase and getDatabase to see how the allowFetch flag already gates the network path, and how cache and the embedded snapshot fallbacks work. The proposal is to add an env setting (e.g. DOCKER_AGENT_OFFLINE or DOCKER_AGENT_MODELS_DEV=off) that makes getDatabase behave as allowFetch=false. Check how existing switches like TELEMETRY_ENABLED are parsed and documented, mirror that, and add a test that the catalog is served from cache/snapshot with no network call. Done: the setting prevents any fetch from https://models.dev/api.json and existing tests still pass.

Written by the indexing model from the issue text.

Description

area/config area/models

What happens

On v1.152.0, docker-agent run downloads the public model catalog from https://models.dev/api.json. That's pkg/modelsdev/store.go, fetchFromAPI. It caches the catalog for 24 hours in $XDG_CACHE_HOME/cagent/models_dev.json. When a deployment gives each session its own HOME, which is common when docker-agent runs as a sandboxed agent runtime, that means one download per new session per day.

The other outbound paths each have a switch:

  • TELEMETRY_ENABLED=false for telemetry;
  • DOCKER_AGENT_AUTO_UPDATE for self-update;
  • DOCKER_AGENT_AUTO_INSTALL=false for tool install;
  • --otel is opt-in.

The catalog download is the one an operator can't turn off.

Why a switch would be enough

The store already handles a failed or blocked download. loadDatabase falls back to the cache, and then to the snapshot embedded at build time (the behaviour #3165 made explicit). So a setting that skips the download and goes straight to cache-or-embedded would only formalise a path that already works.

That matters for deployments that must not make outbound calls beyond the model provider they configured: air-gapped installs, strict egress policies, or self-hosters who want only the calls they asked for.

Proposal

Something like DOCKER_AGENT_OFFLINE=1, or a narrower DOCKER_AGENT_MODELS_DEV=off. It would make getDatabase behave as allowFetch=false: cache if present, otherwise the embedded snapshot, and never the network.

We run docker-agent as one of the agent runtimes in the open-source HarnessRouter. For now, our docs tell self-hosters that it fetches from models.dev and that the host can be blocked. A switch would let us turn it off by default. Thanks for considering it.

Dominant language
Go
Stars
4.7k
Forks
565
Avg merge
18h 52m
Merged PRs (30d)
221

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docker-agent

All issues in docker/docker-agent

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.