OrcaRouter provider support for LLxprt Code

[nissrin2020ali-ux]

LLxprt Code is an open-source, terminal-first coding assistant built around a bet I appreciate: treat every LLM as replaceable rather than locking into one vendor. It lets developers query and edit codebases in the CLI with whichever model fits — a Claude or ChatGPT subscription, a Kimi or Qwen key, or a local llama.cpp instance — and multi-account failover with load-balancer profiles make switching providers practical for daily work.

Because LLxprt Code treats any OpenAI-compatible endpoint as a first-class provider — via the openai alias plus /baseurl, /key, /model — OrcaRouter would add a concrete option for users who want many chat, reasoning, and image models behind one API key, with routing and failover handled upstream. They could stop juggling keys and base URLs and point LLxprt Code at one stable endpoint.

What would you like to be added?

A new optional provider option for OrcaRouter in LLxprt Code, added alongside existing providers rather than replacing any of them. OrcaRouter exposes an OpenAI-compatible API and uses standard API-key authentication, so the natural integration point is the OpenAI-compatible endpoint support LLxprt Code already documents: an orcarouter alias (or a documented /provider openai + /baseurl + /key setup) that users select via /provider, just as they do for OpenRouter or the other gateways in the quick reference. To be clear, this is a proposal for discussion — no code has been written or tested yet.

Why is this needed?

For a tool whose whole point is provider choice, every solid gateway widens that choice. Concretely, an OrcaRouter option would offer:

• Multiple chat, reasoning, image, and video models through one endpoint, with automatic model routing and provider failover when an upstream provider is down or rate-limited.
• Prompt caching to keep long, agentic coding sessions more affordable.
• Usage tracking and budgets — a hard ceiling for developers who pay for their own keys.

All of this rides on the API-key configuration LLxprt Code already uses, so no new machinery should be needed.

Additional context

OrcaRouter is already adopted by other open-source projects in the LLM tooling space — for example goose and OpenCode use it as one more OpenAI-compatible backend for their users. I'm an engineer on the OrcaRouter team, and I'd welcome the maintainers' take on whether this is worth supporting here.

One transparent note: OrcaRouter has an optional open-source partner program in which approved OSS projects can receive a 5% revenue share from usage attributed to their integration. Participation is entirely optional and is not a prerequisite for the integration; I'm happy to follow whatever disclosure or governance requirements LLxprt Code prefers, and the decision is fully yours.

If you're open to the direction, I'd be glad to implement it as a PR following the contribution guidelines — but only after the maintainers approve. More examples of projects built with OrcaRouter: https://www.orcarouter.ai/built-with

[github-actions]

Plan for Issue #3588: OrcaRouter provider support for LLxprt Code

Sizing audit

• Size: small
• Basis:
  • Acceptance criteria: 1 concrete deliverable (add an orcarouter provider alias alongside existing OpenAI-compatible gateway aliases).
  • Package span: exactly one package, packages/providers, plus doc updates in docs/providers/.
  • Phase/epic signal: none; the issue is a single provider-alias addition.
  • Expected net LoC: well under 500. Main work is one new .config file, small doc edits, and a few test assertions.

Summary

• Add a builtin provider alias config for OrcaRouter at packages/providers/src/composition/aliases/orcarouter.config.
• Use baseProvider: "openai" and the OrcaRouter OpenAI-compatible base URL, matching the existing gateway-alias pattern used by openrouter, litellm, etc.
• Document the new alias in:
  • docs/providers/quick-reference.md
  • docs/providers/models-and-limits.md
• Add/extend tests to verify the alias is loaded, registered, and uses the expected default model/base URL.

Test plan

Existing tests to extend

1. packages/cli/test/providers/providerAliases.test.ts

   • Add an assertion that providerManager.listProviders() contains OrcaRouter.
   • Verify the registered provider wraps OpenAIProvider and exposes the expected default model from the new alias config.

2. packages/providers/src/composition/providerAliases.modelDefaults.test.ts

   • Add a small builtin-alias smoke case ensuring loadProviderAliasEntries() returns an entry with alias === 'orcarouter', baseProvider === 'openai', and the expected base-url.

Why no new test file

The existing alias-loading integration test and provider alias unit tests already cover the exact behavior being added: builtin alias discovery, provider registration, and default model propagation. A new file would duplicate that harness.

Implementation steps

1. Create packages/providers/src/composition/aliases/orcarouter.config with:

   • name: OrcaRouter
   • baseProvider: openai
   • base-url: https://api.orcarouter.ai/v1/
   • defaultModel: a stable OrcaRouter chat model ID from the issue/context, or auto if the maintainers prefer a placeholder until model list is confirmed
   • description: short gateway description
   • apiKeyEnv: ORCAROUTER_API_KEY
   • keep it minimal; do not add custom ephemerals unless required

2. Update docs/providers/quick-reference.md:

   • Add OrcaRouter to the builtin provider alias table.
   • Add a short usage example showing /provider orcarouter, /key, and /model.

3. Update docs/providers/models-and-limits.md:

   • Add an orcarouter row under “Default models by alias”.
   • Add a row in the provider summary table with the alias and default model.

4. Extend tests:

   • Add the OrcaRouter presence/default-model assertions in providerAliases.test.ts.
   • Add a builtin alias entry assertion in providerAliases.modelDefaults.test.ts.

5. Run verification:

   • npm run lint:ci
   • npm run lint:eslint-guard
   • npm run typecheck
   • npm run test

Integration analysis

• Used by: Users via /provider orcarouter, profile save/load, and the provider selection UI, exactly like openrouter and litellm.
• Replaces: nothing; this is additive.
• Migration: none. Existing /provider openai + /baseurl workflows continue to work; orcarouter is a convenience alias.
• Access path: builtin alias directory loader in packages/providers/src/composition/providerAliases.ts automatically picks up the new .config file.

Related PRs/issues

• No directly related precomputed candidates were returned by related-candidates.json for this issue.
• Closest existing analog in repo: OpenRouter gateway alias support, implemented via packages/providers/src/composition/aliases/openrouter.config and consumed by packages/providers/src/composition/providerAliases.ts.
• If maintainers want revenue-share disclosure or a governance note, it should be recorded outside code, e.g. issue/PR metadata, rather than in the provider alias implementation.

Prompt for AI agents

Implement the OrcaRouter alias as a minimal builtin gateway profile modeled on openrouter.config and litellm.config. Do not introduce new provider machinery, auth flows, or runtime code. Keep changes confined to one builtin alias config, doc updates, and existing alias-loading tests. Preserve current lint/typecheck/test invariants; do not add suppression directives or downgrade rules.

[acoliver]

@nissrin2020ali-ux I think this is simple just another provider conf file. feel free to submit a PR. I'd be happy to include it in 0.12.0