orizon-connect

Connect your application to the Orizon optimisation gateway. The CLI provisions a project, writes everything you need to ./orizon.config.json (your token plus a provider map), and lets you route multiple providers through one gateway link — no change to your request format.

Provision

npx orizon-connect                       # interactive: project name → invite code
npx orizon-connect --name acme --code <invite-code>

This writes ./orizon.config.json:

{
  "project_id": "…",
  "name": "acme",
  "token": "orz_live_…",
  "gateway": "https://<your-gateway>",
  "providers": {
    "openai":    { "upstream": "https://api.openai.com/v1",                        "url": "https://<gateway>/openai" },
    "anthropic": { "upstream": "https://api.anthropic.com/v1",                     "url": "https://<gateway>/anthropic" },
    "google":    { "upstream": "https://generativelanguage.googleapis.com/v1beta/openai", "url": "https://<gateway>/google" }
  }
}

Already have a token?

If a client was onboarded before (or already talks to one provider) and just has a token, regenerate the full orizon.config.json — with every provider URL — without re-provisioning. The project name is inferred from the token:

npx orizon-connect config --token orz_live_…

(--name <n> optionally overrides the inferred name.)

Wire it up (multi-provider, one link)

Providers are path-scoped: point each provider's OpenAI-compatible client at providers.<name>.url, keep its own key, and add the X-Orizon-Token header. Nothing in your request body changes.

from openai import OpenAI
cfg = json.load(open("orizon.config.json"))
h = {"X-Orizon-Token": cfg["token"]}

openai_client    = OpenAI(base_url=cfg["providers"]["openai"]["url"],    api_key=OPENAI_KEY,    default_headers=h)
anthropic_client = OpenAI(base_url=cfg["providers"]["anthropic"]["url"], api_key=ANTHROPIC_KEY, default_headers=h)
google_client    = OpenAI(base_url=cfg["providers"]["google"]["url"],   api_key=GEMINI_KEY,    default_headers=h)

The gateway is a pass-through proxy: your provider key rides the Authorization header straight to that provider and is never stored. X-Orizon-Token scopes traces, optimisations, and the dashboard to your project.

When X-Orizon-Token is required

There is one asymmetry worth knowing, because getting it wrong produces a 404 rather than a helpful error:

| Provider | X-Orizon-Token | Why | | -- | -- | -- | | Built-in (openai, anthropic, google) | optional | The gateway knows the upstream already. Without a token the request still proxies; it just isn't scoped to your project, so it won't appear on your dashboard. | | Custom (anything you added with set-url) | required | Your custom providers are stored on your project. Without the token the gateway cannot resolve the name and returns 404 Unknown provider. |

Send it always and you never have to think about it.

Custom providers

Any OpenAI-compatible provider works — add it once and it routes like a built-in:

npx orizon-connect set-url bedrock-us-west-2 https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1
npx orizon-connect set-url groq https://api.groq.com/openai/v1

Names may contain letters, digits, underscores and hyphens (bedrock-eu-central-1 is fine). A handful of names reserved by the gateway — api, v1, healthz — are rejected outright rather than silently accepted.

Register the base URL exactly as that provider documents it, including its version segment. The gateway joins your registered base to whatever path your SDK sends and never guesses at the missing piece — it cannot, because Google (…/v1beta/openai) and Groq (…/openai) have identical-looking base URLs and opposite correct answers. Registering a base one segment short still works (the gateway recognises the endpoint from the path shape and logs a warning), but registering it correctly is one less thing to debug.

Registering a provider merges — it never deletes providers you added earlier from another machine.

Amazon Bedrock? There is a dedicated walkthrough covering the AWS side too — model access, API keys (SigV4 will not work through any proxy), and the errors you are likely to hit: docs/bedrock-onboarding.md in the gateway repo.

Anthropic SDK — native drop-in

The stock Anthropic SDK needs no code change: point its base URL at the gateway and keep your x-api-key. The gateway serves /v1/messages + /{provider}/messages natively, forwards the body byte-for-byte (so cache_control prompt caching is preserved), and — for the built-in anthropic provider — requires no X-Orizon-Token (see the table above; a custom provider always needs one).

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ baseURL: cfg.providers.anthropic.url });
// or purely by env: ANTHROPIC_BASE_URL=https://<gateway>/anthropic  (or /v1)

Fail over if the gateway is down — withFallback

A fully-down gateway can only be bypassed client-side. This package also exports withFallback(): wrap the SDK's fetch and requests try the gateway first, then the provider's real upstream if it's unreachable (same method/headers/body — keys are pass-through). No forked SDK.

import { withFallback } from "orizon-connect";
import cfg from "./orizon.config.json" assert { type: "json" };

const client = new Anthropic({
  baseURL: cfg.providers.anthropic.url,
  fetch: withFallback(cfg),   // → api.anthropic.com if the gateway is down
});

Works the same for the OpenAI SDK. Fails over on a network error / timeout or a gateway 502/503/504; a 4xx/500 is surfaced as-is. Options: withFallback(cfg, { timeoutMs, fallbackStatuses, onFallback, fetch }).

Manage

# Delete the project (uses ./orizon.config.json, or pass explicitly)
npx orizon-connect delete
npx orizon-connect delete --project <id> --token <token>

# Add a custom provider (starts with an empty upstream), then set/switch its URL
npx orizon-connect generate mistral
npx orizon-connect set-url mistral https://api.mistral.ai/v1

generate adds a provider to orizon.config.json; set-url fills its upstream and syncs it to the gateway so https://<gateway>/mistral starts routing. set-url also switches the URL of an existing provider.

Flags: --gateway <url> (defaults to the hosted Orizon gateway; override with ORIZON_GATEWAY). The built-in providers (openai / anthropic / google) are defined gateway-side — the config just tells your app which URL to use for each.