Tiers and Priority

CUST/OS uses two provider fields to control selection:

• taskPriority sets the order in which eligible providers are tried.
• tier describes where a provider runs and which security modes allow it.

Set tier and priority independently

taskPriority is an integer. Lower numbers are tried first among eligible, healthy providers.

tier is one of six labels describing the provider's physical location and connection to the operator. Security modes use this label to filter providers before selection.

You can have:

• Two providers in the same tier with different priorities (e.g., two cloud LLMs you want to fail over between).
• Providers in different tiers with their own priorities (e.g., handheld at priority 1 and cloud at priority 5).
• A single provider whose tier determines whether a security mode permits it.

Changing a tier filter does not require changing the priority numbers.

The six tiers

Tier labels describe the deployment relationship. Actual latency depends on the model, hardware, prompt, and connection; the tier alone does not predict response time.

Security modes (lockdown)

The security.mode field selects a lockdown mode that filters which tiers are allowed:

The router uses the mode to filter inference providers for chat, embedding, transcription, TTS, and vision. It does not disable radios or control unrelated device traffic.

The NavBar carries a security mode button that lets the operator switch modes with a single tap (e.g., "enter EMCON now") without editing the config file.

What tier drives beyond lockdown

Classification ceilings

Providers without an explicit classification field default to UNCLASSIFIED for the cloud tier and to the operator's configured clearance level for other tiers. Review these defaults when configuring a deployment.

Per-tier budget defaults

defaults:
  byTier:
    handheld:
      requestTimeoutMs: 30000
      maxTokens: 1024
    cloud:
      requestTimeoutMs: 120000
      maxTokens: 4096

Per-provider values still win. Tier values fill in where providers do not specify their own.

Tier-aware hooks

Hook rules can target specific tiers:

hooks:
  rules:
    - event: PreToolUse
      toolPattern: "send_*"
      whenTier: ["cloud", "command-post"]
      action: require_approval
      reason: "Comms tools require approval when reasoning at remote tiers"

This fires only when the active inference provider is in the cloud or command-post tier.

Fallback grouping

agent.fallbackMode controls how providers are ordered:

• priority (default) -- flat sort by taskPriority.
• tier-grouped -- sort by tier order (handheld, pack, mobile, mounted, command-post, cloud) first, then by taskPriority within each tier. The entire handheld tier is tried before any pack provider.

Delegation gating

Standalone, EMCON, squad-only, and field-only modes implicitly disable cross-device delegation because they exclude command-post from the allowed tier set.

Voice pipeline

Voice providers use the same tier filter as other model requests. In emcon mode, only handheld and pack providers are eligible, so a cloud STT provider is skipped. Configure a local speech provider if voice needs to remain available in that mode.

Audit

Every inference request is logged with its tier. The Audit panel's "By Tier" view shows call counts and token totals grouped by tier, so operators can see how much reasoning happened at each level.

How tier and priority compose

A representative config:

agent:
  fallbackMode: tier-grouped

security:
  mode: emcon

providers:
  - name: "local"
    tier: "handheld"
    taskPriority: 1
  - name: "ruck-jetson"
    tier: "pack"
    taskPriority: 3
  - name: "lan"
    tier: "mobile"
    taskPriority: 5
  - name: "vehicle"
    tier: "mounted"
    taskPriority: 10
  - name: "cp"
    tier: "command-post"
    taskPriority: 50
  - name: "claude"
    tier: "cloud"
    taskPriority: 100

What happens on each call:

1. Tier filter runs first. mode: emcon removes everything except handheld and pack. Only local and ruck-jetson are in the running.
2. Sort orders the survivors by tier-grouped order (handheld first, then pack).
3. Health check decides whether local is callable.
4. Classification boundary clamps which providers can see the operator's data.
5. Hook rules are evaluated -- whenTier matches do not fire because we are at handheld or pack, not cloud or command-post.
6. The call goes out.

Changing mode: emcon to mode: normal permits all configured tiers. Health and classification checks still apply. With tier-grouped fallback, the router tries tiers in the order shown above.

How to set tier correctly

Choose the tier that matches the provider's physical location and connection:

• A file:// URL pointing at a model on the device is handheld.
• An http:// URL pointing at a wired peripheral the operator carries on their body (USB-tethered Jetson, Ethernet-connected Pi in a chest rig) is pack.
• An http:// URL pointing at a companion device the squad carries is mobile.
• An http:// URL pointing at a vehicle compute platform is mounted.
• A cot:// URL or any provider reachable over the TAK mesh is command-post.
• An https:// URL pointing at someone else's data center is cloud.

Check the assigned tiers against the security modes you plan to use. A remote endpoint labeled handheld would remain eligible in standalone mode, so accurate labels are required for the filter to behave as intended.

See also

• Reference: Configuration
• Reference: Providers
• Explanation: On-device inference