Skip to main content

Osaurus Router

Osaurus Router is the hosted inference path for Osaurus accounts. It's an OpenAI-compatible remote provider that Osaurus wires up for you automatically once you have an identity — so you can reach hosted models from the same model picker, chat, and agent loop as everything else, without pasting an API key.

Think of it as the batteries-included cloud option:

  • Local MLX models and Apple Foundation Models cover the fully-offline case.
  • Your own provider keys (Remote Providers) cover bring-your-own-cloud.
  • Router covers "I just want a capable hosted model with zero setup."

Your agents, memory, and tools work the same across all three.

How it connects​

Router availability follows your local Osaurus identity. When an identity is present, the Router provider is injected into your remote provider list and becomes eligible for the same model picker and chat paths as any other provider. Connection stays automatic:

  • It connects on app launch alongside your other auto-connect providers.
  • Signing in or changing identity reconnects Router automatically — no manual refresh.
  • Waking the Mac or recovering network connectivity retries discovery on its own.
  • Transient connect failures retry quietly; authentication and contract errors surface as real, terminal errors rather than spinning forever.

Using Router​

Once connected, Router's models appear in the model picker grouped under Osaurus Router, right alongside your local and other cloud models. Pick one and chat, or target it from an agent — it speaks standard OpenAI Chat Completions, so streaming and tool calling work exactly as they do elsewhere.

A couple of reliability details Osaurus handles for you:

  • Sensible output length. If a request doesn't specify max_tokens, Osaurus sends a sane default so a long agent run isn't silently truncated by an upstream cap.
  • No silent empty answers. If a response finishes without producing any visible text, Osaurus shows an explicit empty-response notice instead of dropping the bubble.

Billing and your privacy​

Router is metered, so a few things are tracked — but only metadata, never your content. Prompt text, responses, tool arguments, and tool results are never written to billing records.

  • Retries are de-duplicated. A reconnect or automatic retry won't double-bill the same logical step; a Retry you initiate starts a fresh run.
  • Local, encrypted ledger. Router charges are also recorded on your Mac at ~/.osaurus/billing/ledger.sqlite, encrypted with your storage key (SQLCipher), keeping the newest 10,000 rows for up to 365 days. This lets support debug "I was charged but saw nothing" reports without any transcripts ever leaving your machine. Each row carries correlation data (request id, model, token counts, cost, status, and how the turn rendered) — no prompt or response text. You can export a metadata-only diagnostic from the Dashboard.
  • Remote Providers — connect your own OpenAI, Anthropic, Gemini, and other provider keys
  • Models — how local, Apple Foundation, and cloud models share one picker
  • Identity — the cryptographic identity Router availability depends on
  • HTTP API — the OpenAI-compatible surface Router uses under the hood