npm
npm install orbitrageLicense
Apache-2.0 · Node >= 18
Install
openai (>=4) is the only peer you need:
Initialize
Callinit() once, at the very top of your program, before importing your LLM
client. It returns a promise — await it.
What init() does
- Generates a stable trace id and adds it to every request as
x-orbitrage-run-id. - Installs a global
fetchinterceptor that injects trace + user headers on any request to an Orbitrage host. This is the primary mechanism and works even in frozen-ESM environments like Next.js. - Best-effort patches the
OpenAIconstructor and setsOPENAI_BASE_URLso no-arg clients point at the gateway. Your explicitbaseURLorapiKeyalways wins.
OrbitrageConfig
string
required
Your
orb_ key. Falls back to ORBITRAGE_API_KEY.string
End-user id to attribute calls to (sets
x-orbitrage-end-user-id).string
Override the gateway URL. Defaults to
https://api.orbitrage.ai/v1 (or
ORBITRAGE_BASE_URL).boolean
default:"true"
Set
false to make init() a no-op.boolean
default:"false"
Suppress the startup log line.
init() is idempotent. Legacy v0.4 options (disableBatch, captureContent,
instruments, …) are accepted and ignored.Per-end-user attribution
Forcing a model
Pinning a frontier model (
claude-*, gpt-*, gemini-*, grok-*) requires an
enabled key for that vendor — the call runs on your provider account and
Orbitrage bills $0. Without one it throws a 403 with code byok_key_required.
See BYOK.API surface
Using a framework?
LangChain, the Vercel AI SDK, Mastra, and others use the OpenAI client (orfetch) under the hood, so they’re captured transparently. See
Integrations.