← Tutorials

Add a Cloud LLM Provider

This optional tutorial adds an Anthropic Claude provider, stores its API key, and checks provider selection. Use it for deployments that permit cloud inference.

You should have completed Getting Started first.

What you will learn

  • How to add a provider to custos.yaml
  • How to store an API key in the encrypted credential store
  • How taskPriority decides which provider wins when several are available
  • How to verify the provider is healthy from the Status panel

Step 1 -- Open custos.yaml

  1. Tap the Settings icon in the NavBar.
  2. Tap Edit Configuration. The in-app editor opens with custos.yaml loaded.

Step 2 -- Add the Anthropic provider

Scroll to the providers: list. Add a new entry:

providers:
  - name: "anthropic-claude"
    task: "chat"
    protocol: "anthropic"
    url: "https://api.anthropic.com"
    model: "claude-sonnet-4-6"
    taskPriority: 1
    tier: "cloud"
    classification: "UNCLASSIFIED"
    auth: true

Field-by-field:

Field Purpose
name Unique identifier for this provider
task chat, embedding, transcription, tts, vision, or detection
protocol Which protocol to use -- openai, anthropic, ollama, litert, cot, vision
url Base URL of the API endpoint
model The model identifier the provider expects
taskPriority Lower number wins. 1 makes this the preferred chat provider
tier Trust/reachability environment: handheld, pack, mobile, mounted, command-post, cloud
classification Highest data classification this provider may handle
auth Set true if this provider needs an API key

Tap Save. The config reloads and the new provider appears in the Status panel.

Step 3 -- Set the API key

Cloud providers need a key. CUST/OS does NOT read keys from custos.yaml -- that file lives on shared storage. Keys are stored in the device's encrypted keystore, keyed by provider name.

On the device:

  1. Tap the Status icon in the NavBar.
  2. Find the row for anthropic-claude -- it'll be offline because there's no key yet.
  3. Tap the row. The provider detail dialog opens.
  4. Tap Set Key, paste your key, confirm.

The provider is checked again after the key is saved. If it stays offline, open its details for the error. Use Change Key to replace a key or Remove Key to delete it from the store.

From a workstation (for unattended deploys):

Your integrator can push keys via adb to the encrypted store. See your deployment guide for the exact procedure.

Keys entered through CUST/OS are stored in encrypted preferences backed by Android Keystore.

Step 4 -- Verify with the Status panel

Tap the Status icon in the NavBar. You will see one row per provider, grouped by task. Each row shows:

  • Provider name and protocol
  • Tier
  • Health status: online, slow, offline, or error
  • Latency of the most recent health check

If anthropic-claude shows online, you are done. If it shows an error, tap the row for details -- most often it is an unauthorized response (bad key) or a model name typo.

Step 5 -- Watch routing in action

Send a message in chat. The streaming indicator at the top shows which provider was used.

If you have two chat providers and both are online, CUST/OS picks the one with the lower taskPriority. If the preferred provider fails repeatedly, the router automatically falls back to the next-priority provider for a short cooldown (about a minute) before retrying the primary.

Step 6 -- Per-provider overrides (optional)

Most defaults come from the top-level defaults: block, but you can override them per provider:

  - name: "anthropic-claude"
    task: "chat"
    protocol: "anthropic"
    url: "https://api.anthropic.com"
    model: "claude-sonnet-4-6"
    taskPriority: 1
    tier: "cloud"
    classification: "UNCLASSIFIED"
    auth: true
    requestTimeoutMs: 120000
    maxTokens: 4096

What you learned

  • Providers are added by editing custos.yaml and saving -- no rebuild needed.
  • API keys live in the encrypted keystore, never in YAML.
  • taskPriority decides which provider wins when several are healthy.
  • The Status panel surfaces health, latency, and errors.
  • Per-provider overrides let you tune timeouts and token limits.

Where to go next