> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Models & runtime
> Model tiers and cross-provider failover, bringing your own key or provider, delegated subagents, and how tool calls are batched.
Agents run in an isolated sandbox on a model Clarion resolves per run. You can leave that entirely to us, pin a model, bring your own key, or point the whole workspace at your own provider endpoint.
## Tiers, not model names
Callers inside Clarion ask for a **capability tier** rather than a specific model, so a model generation change is one config edit and not a sweep through the codebase.
| Tier | For |
| ---------- | ------------------------------------------------------------------------------------------ |
| **Light** | Cheap, high-volume classification and mechanical steps. |
| **Medium** | The default investigative work. |
| **Strong** | The hardest reasoning — correlation across systems, ambiguous evidence, response planning. |
Each tier resolves to an ordered chain of concrete `provider/model` candidates.
## Model failover
Every tier's chain pairs a **primary** with a **cross-provider failover**. When the primary hits a model-access failure — a provider outage, a capacity error, a model withdrawn — the run moves to the next candidate instead of failing.
The failover is deliberately on a *different* provider. A failover to a sibling model on the same provider does not survive the failure mode that actually takes models offline.
Candidates are compared canonically, so a bare model id and its `provider/`-prefixed twin collapse to one entry — the chain never retries the model that just failed under a different spelling.
## Bring your own key (BYOK)
Enable BYOK for the workspace and paste an Anthropic or OpenAI API key in [Settings → Workspace](/learn/settings/workspace). Clarion infers the provider from the key prefix.
A workspace with its own usable key runs **only** on that key:
* No cross-subsidy — your inference is billed to you.
* No tenant data through Clarion's provider account.
* A run fails terminally rather than silently falling back to a Clarion key.
The key never enters the sandbox. Agent traffic goes through Clarion's proxy, which attaches the credential host-side.
Because a single-provider workspace has no second provider to fail over to, its tier chain is failover-free: each tier resolves to the suggested model for that provider. Clarion checks at save time that the key can serve every tier. A BYOK-enabled workspace with **no** usable key still runs on the Clarion chain, so enabling the flag before pasting a key never takes the workspace down.
## What the sandbox can run
Agent runs execute in the **opencode** harness inside the sandbox. Clarion generates the harness's provider configuration per run, which is why the set of usable models is not a fixed allowlist: it is every model opencode can be pointed at over one of the three wire protocols below. Naming a new model on a provider you already registered needs no Clarion release.
## Bring your own provider
Beyond the two platform providers, a workspace can register credentials for **any** provider that speaks one of three wire protocols:
| Protocol | Providers |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `anthropic-messages` | Anthropic |
| `openai-responses` | OpenAI |
| `openai-chat` | OpenRouter, DeepSeek, Groq, Fireworks AI, Together AI, and anything else OpenAI-compatible |
The picker prefills protocol and endpoint for the curated providers, and a **custom** entry covers anything not listed — you supply the base URL and key. Clarion can list the endpoint's models to confirm the credential works before saving.
A registered provider becomes addressable as `provider/model` anywhere a model is named. Any provider other than the two platform ones **requires** a stored credential: the proxy fails closed rather than reaching an unconfigured provider with a platform key.
Provider endpoints must be public HTTPS hosts. Clarion rejects loopback, private-range, link-local, and cloud-metadata addresses.
## Models settings
Workspaces with the BYO Models capability get **Settings → Models**, where you can see the resolved chain and override the model per tier. Without the capability the route is hidden and the workspace runs the platform defaults.
## Subagents
An agent run can **delegate** to a subagent lane — a scoped worker with its own instructions, its own tool subset, and optionally its own model. Lanes are how a run does breadth-first exploration or a mechanical sweep without spending frontier-model context on it.
What matters about Clarion's implementation is where the decision is made: **the trusted backend resolves the lanes, not the sandbox.** Before the run starts, Clarion decides what each lane is, expands its tool scope against the tools the run can actually call, and stamps the answer onto the job. The sandbox receives a resolved answer rather than a declaration it could reinterpret.
Two consequences follow:
* A lane whose tool scope cannot be expressed is **dropped**, not silently degraded. A subagent with an empty toolset is a failure that looks like success, so it is made visible instead.
* A lane bound to a non-inherited model has that model resolved to a concrete `provider/model` up front, under the same BYOK policy as the parent. A binding that cannot be resolved drops the lane — running a cheap-tier sweep on the frontier model, or a BYOK tenant's traffic on a Clarion key, are both worse outcomes than the lane not existing.
Which lanes a workspace's agents may delegate to is itself configurable.
## Tool-call batching
Round trips, not tokens, are what make a long investigation slow. Clarion's tool schemas are written so an agent asks for everything it needs in **one** call rather than one call per item:
* **`get_skill`** takes a list of skill ids. Skills are independent, so batching them costs one round trip instead of one each — and every skill in the batch renders in the run transcript.
* **`record_inferred_asset`** takes every asset an investigation turned up in a single call, up to 50. Duplicates inside a batch collapse to one row.
* **MCP server decisions** are batched by verdict: one call approves or denies many servers, and the result reports per-server outcome so a partly-landed batch is still legible.
* **Clarifications** are batched: several related questions reach the responder together, each labelled with its position in the batch.
* **Tool catalog lookups** batch ids, so a multi-capability triage resolves its whole tool surface at once.
A batched call that partly fails returns what succeeded alongside what didn't, rather than discarding the whole batch — which is the guarantee batching exists to provide.
Where BYOK and workspace instructions live.
The agent templates that run on this stack.