Models and routing

How Oktapod uses the AI account you connect, picks a model for each task, falls back when a provider fails, and tracks usage.

A model is the AI that does the reasoning. Oktapod does not include one; it uses the account you connect. A model is separate from your apps: connecting a model does not give Oktapod your email, and connecting email does not give it a model.

#Connect a model

The first model is connected during setup. See First run for the choices. To add or change one later:

• In the web app, use Settings → Advanced → System setup, or look at Settings → Apps & permissions → Models.
• In a terminal, run oktapod setup, or oktapod onboard --manual for every option.

When you add a model provider from the web app, it joins automatic routing and the app asks you to restart Oktapod (oktapod restart) to activate it.

When you select a different model through a local Codex or Claude Code CLI, Oktapod checks that the account can use it. Claude's check uses a tiny test message with no tools or conversation history. If the selected model is unavailable or the CLI is obsolete, Oktapod updates the CLI using its existing installer and release channel, then checks again. Sign-in, quota, network, timeout, and unreadable-response failures show recovery instructions instead. If the update fails, updates are disabled, or the installation needs manual maintenance, it keeps your current model and shows repair instructions. Selecting the same model again performs no update. The update does not grant model access: if your account still cannot use the model, open the CLI once to check sign-in and availability.

#Automatic routing

By default, Oktapod picks a model for each task. It first classifies the request as simple, moderate, or complex using a fast model, then answers with your provider's fast, balanced, or deep model to match. If the classification is not confident, it uses the deeper model.

• Risk only raises the bar. A risky action can require a deeper model, but a model choice never grants permission. Approvals still apply.
• Attachments count. If a task includes an image or PDF, Oktapod picks a model that can read it, or uses extracted text with citations. If neither is possible, it says so.
• One-model setups are fine. With a single local model, every task uses it.
• Every choice is recorded, including which model ran and how much effort it was asked for.

To always use one model instead:

oktapod models routing pinned
oktapod models set --provider <provider> --model <model>

Switch back with oktapod models routing automatic. A pinned model that cannot handle a request fails instead of quietly switching to another provider.

#Fallback

You can connect more than one provider. If one is unavailable, times out, or is rate limited, Oktapod tries the next compatible one. Errors that would fail again the same way, such as a bad key or an invalid request, are not retried over and over.

oktapod models status --verbose
oktapod models list

#Usage and cost

oktapod usage
oktapod usage --days 30

Oktapod records every model call it makes, including tokens where the provider reports them. When a number is not known, it is shown as unknown, never as zero. This is your own record, not a provider invoice; check billing and quotas with the provider. In the web app, see Settings → Advanced → Usage.

#Privacy

A model request can include your message, relevant memory, and attachments you shared. The provider you connect receives that data under its own terms. A local model keeps requests on hardware you control.

Full prompt logging is off by default. Turn it on only for short debugging sessions:

oktapod prompt-logging status

To see why a model was chosen without reading prompts, use oktapod decision <run_id>.

#Common problems

#Background subscription CLI repair

To let model discovery update an installed Codex or Claude CLI before testing a new model, enable:

oktapod config set runtime.models.cli_auto_update --value true --json-value

This defaults to false. Set it back to false to stop background CLI updates. Discovery still needs automatic task routing and promotion mode. CLI version pins and disabled-update settings take precedence. An updated CLI must pass the same model quality evaluation before Oktapod promotes the model.

Sign-in, quota, network, and timeout failures give recovery instructions instead of running an updater. Known npm, Homebrew, native Claude, and Claude WinGet installations keep their existing installer. Custom installations require a manual update. A crashed updater lock can recover after three minutes when both its owner and installer have exited. Unknown or active locks stay protected.