#8684 `PI_OFFLINE` silently disables all provider model discovery — undocumented behavior contradicting its documented scope · pi

What happened?

PI_OFFLINE is documented as disabling only startup housekeeping network operations (update checks, package update checks, install/update telemetry). In practice, it also disables all provider model-catalog network discovery for the entire session — this is undocumented and easy to hit by accident.

Verified this is core behavior, not an extension issue, by reading the source directly (not just via pi -ne, since the affected code path doesn't touch any extension at all):

packages/coding-agent/src/core/model-runtime.ts, lines 190–196:

ts const runtime = new ModelRuntime( credentials, config, modelsPath, modelsStore, providers, process.env.PI_OFFLINE === undefined, // becomes `modelNetworkEnabled` );

That value is stored as modelNetworkEnabled and used as the default allowNetwork for every model refresh, line 701:

ts const refreshOptions = { ...options, allowNetwork: options.allowNetwork ?? this.modelNetworkEnabled, };

So merely having PI_OFFLINE set in the environment (to any value — the check is === undefined, not a truthiness/1 check, so even PI_OFFLINE=0 or PI_OFFLINE= triggers it) disables network-based model discovery everywhere that doesn't explicitly override allowNetwork: true. Providers relying on the default refresh path never discover models for the whole session, with no error and no indication this is what happened.

This contradicts the documented scope of PI_OFFLINE:

packages/coding-agent/docs/settings.md, line 84: "Use --offline or PI_OFFLINE=1 to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry." (model discovery is not "described here")
packages/coding-agent/docs/environment-variables.md, line 84: "Disable startup network operations, including update checks, package updates, and install/update telemetry" (same omission)
packages/coding-agent/src/cli/args.ts, line 433 (--help text): "Disable startup network operations when set to 1/true/yes" (same omission)

It's also inconsistent with pi's own built-in llama extension, which deliberately keeps user-initiated model discovery alive under PI_OFFLINE:

https://github.com/earendil-works/pi/blob/v0.84.3/packages/coding-agent/src/extensions/llama/index.ts#L54-L58

That comment establishes the intended contract: PI_OFFLINE should suppress automatic/startup network access, while a user-initiated action against an explicitly-configured provider is a sanctioned exception. The modelNetworkEnabled default in model-runtime.ts applies the offline gate much more broadly than that — any provider/extension that doesn't specially override allowNetwork: true (as llama does) loses discovery entirely, including in response to explicit user actions like opening /model.

This matters in practice for anyone setting PI_OFFLINE=1 purely for its documented purpose — e.g. in an immutable/sandboxed environment (such as a DDEV add-on) to suppress update-check/telemetry phone-home — who then finds an explicitly configured, reachable model provider shows zero models with no explanation.

Steps to reproduce

. Configure any provider that relies on network model discovery through the default ModelRuntime.refresh() path (not one that special-cases allowNetwork: true like llama does) — e.g. the litellm provider via LITELLM_BASE_URL/LITELLM_API_KEY from the pi-provider-litellm extension, pointed at a real, reachable endpoint. 2. Set PI_OFFLINE=1 in the environment. 3. Run pi --list-models (or start pi interactively and open /model).

Result: no models are discovered, with no error message referencing PI_OFFLINE or offline mode anywhere.

Unset PI_OFFLINE and repeat step 3 with identical configuration: models are discovered normally.

PI_OFFLINE=1 LITELLM_BASE_URL="https://your-litellm-proxy.example.com" LITELLM_API_KEY="sk-..." pi --list-models
// -> "No models available." — no mention of PI_OFFLINE/offline anywhere

env -u PI_OFFLINE LITELLM_BASE_URL="https://your-litellm-proxy.example.com" LITELLM_API_KEY="sk-..." pi --list-models
//  -> lists all discovered models
```

Expected behavior

One of:

PI_OFFLINE's documentation (settings.md, environment-variables.md, --help text) explicitly states that it also disables automatic model-catalog network discovery, so this isn't a surprise; and/or
Model-network gating is decoupled from PI_OFFLINE into its own flag, since users set PI_OFFLINE for its documented, narrower purpose (no update/telemetry phone-home) and don't expect it to also silently break model discovery for an explicitly configured provider; and/or
The modelNetworkEnabled default is narrowed to match the llama extension's contract: suppress only automatic/startup discovery under PI_OFFLINE, while still allowing user-initiated discovery (e.g. opening /model) to proceed, consistent with the exception llama already carves out for itself.

At minimum, when discovery is skipped due to PI_OFFLINE, this should be surfaced to the user (or to extensions, via the refresh result) rather than failing indistinguishably from "not configured" or "provider unreachable".

Version

0.84.3