A Running Ollama Server Does Not Mean Your APX Model Is Healthy

A process can be alive while the capability you need is missing. For a local AI runtime, that distinction matters: an Ollama server answering HTTP requests does not prove that the configured model is installed.

APX treats those as separate facts. When routing a turn to an Ollama model, it checks both the server and the candidate model before accepting the route.

This is a small reliability rule with a broad lesson: health checks should test the dependency your operation actually requires, not merely the service around it.

The false-positive health check

Imagine this APX configuration:

{
  "super_agent": {
    "model": "ollama:qwen3:8b",
    "model_fallback": {
      "models": ["openrouter:openrouter/free"]
    }
  }
}

Ollama may answer GET /api/tags successfully while qwen3:8b is absent. A simple status-code check would mark Ollama healthy, select it, and delay failure until the actual model call. The router would have made a confident decision using incomplete evidence.

APX instead passes the candidate model into the provider health check. Its Ollama adapter reads the models returned by /api/tags and verifies that the requested model is available. If the server responds but the model is missing, the result is unhealthy for that route and includes the available model names for diagnosis.

The configured fallback chain can then continue naturally. No manual edit is needed just because a daemon was reachable but incomplete.

Why this belongs in APX, not APC

Agent Project Context (APC) is the portable context layer. It keeps durable project instructions, agent definitions, skills, and safe configuration hints in the repository. A project may state which model an agent should use, but it cannot guarantee that a particular machine has pulled that local model.

APX is the daily-use runtime and tooling layer. It knows the current machine, configured engines, credentials, endpoints, and locally available Ollama models. That makes APX the right place to turn a portable preference into a runtime decision.

Keeping this boundary clear prevents two bad outcomes. First, APC does not accumulate machine-specific availability state. Second, APX does not treat repository configuration as proof that an external capability exists.

Health must match the routing question

Different callers can ask different health questions. A general status screen may only need to know whether Ollama responds. A router evaluating ollama:qwen3:8b needs a stricter answer: can this provider serve this model now?

APX supports that distinction. Without a candidate model, the Ollama health probe can remain loose and report server reachability. With a candidate, it validates model presence. The router uses the strict form while walking its ordered model chain.

This avoids making every health probe unnecessarily expensive or specific, while still protecting the execution path that matters.

A practical design rule

When adding health checks to any agent runtime, write down the decision they guard.

• If the decision is "show provider online," reachability may be enough.
• If the decision is "send this turn to this model," verify that model.
• If the decision is "run this tool," verify the tool's required dependency, not only its host process.

Also preserve diagnostic detail. "Unhealthy" is less useful than "server running; configured model not loaded." APX keeps the attempted models and reasons, so fallback behavior remains observable rather than mysterious.

Portable context gives every machine the same intent. Runtime-aware health checks let each machine execute that intent honestly.