Skip to main content

Connect your tools (anyray-connect)

anyray-connect is the on-ramp CLI. It points your local coding tools and your SDK/shell environment at the Anyray gateway by writing each tool's base URL and a placeholder API key. That's all it does — the gateway stays the brain (routing, spend store, content encryption, optimizer), and anyray-connect just captures your tools onto the path.

It replaces the manual base-URL exports from Using the SDKs with one idempotent command. The manual steps still work as a fallback.

:::info This is the client-side on-ramp, not the installer anyray-connect does not install or run the stack. Your admin still installs and updates Anyray with docker compose up -d (see Org Admin → Install). anyray-connect only points an already-running gateway's clients at it. :::

Run it​

npx anyray-connect --gateway https://gw.yourorg.internal --user you@yourorg.com

anyray-connect is a small, dependency-free Node CLI (ESM, v0.1.0). It detects the tools you have, shows you the plan, asks for confirmation, and writes the changes. It's idempotent — safe to re-run — and --revert cleans up everything it wrote.

What it writes​

The real provider key is never written here — it stays server-side in the gateway (ANYRAY_PROVIDER_KEY_*), which swaps it in per request. anyray-connect only writes a placeholder key plus content-free attribution metadata (x-anyray-metadata with user/team). Prompt and response content is never touched or logged.

ToolModeWhat changes
Claude CodeAutomaticWrites the env block in ~/.claude/settings.json: ANTHROPIC_BASE_URL (gateway origin), ANTHROPIC_AUTH_TOKEN (placeholder), and ANTHROPIC_CUSTOM_HEADERS carrying x-anyray-provider: anthropic and x-anyray-metadata (your user/team). Merges only its own keys; takes a one-time backup at settings.json.anyray-bak.
Codex CLIAutomaticWrites a managed [profiles.anyray] + [model_providers.anyray] block in ~/.codex/config.toml (respects $CODEX_HOME): base URL <gateway>/v1 over the Responses wire API, the placeholder key, and x-anyray-metadata headers (stamped intent: codex by default; override via ANYRAY_CODEX_INTENT). --revert removes only the Anyray sections.
Shell envAutomaticWrites a managed, delimited block (# >>> anyray connect >>> … # <<< anyray connect <<<) into ~/.zshrc / ~/.bashrc / ~/.profile: exports OPENAI_BASE_URL=<gateway>/v1, OPENAI_API_KEY=<placeholder>, ANTHROPIC_BASE_URL=<gateway>, ANTHROPIC_AUTH_TOKEN=<placeholder>. Covers SDK jobs and scripts. Re-running replaces the block; --revert removes it.
CursorManualPrints the exact UI steps: Cursor → Settings → Models → OpenAI API Key; Base URL = <gateway>/v1, key = placeholder, optional x-anyray-metadata header. Cursor's config is app state we don't script.
WindsurfManualSame idea — prints the exact Windsurf settings steps.

:::note Shell env and per-user attribution The shell-env block sets only standard SDK env vars, which don't carry custom headers — so plain shell-env does not attach per-user x-anyray-metadata. Claude Code (which supports custom headers) does. For attributed SDK traffic, set x-anyray-metadata explicitly on your requests (see Using the SDKs). :::

Flags​

--gateway <url>     Gateway origin (default: $ANYRAY_GATEWAY_URL or http://localhost:8787)
--user <id>         Attribute spend to this user (default: git user.email, else OS username)
--team <id>         Attribute spend to this team
--intent <id>       Tag this traffic with an intent (filterable as intent:<id> in the console)
--intent-label <s>  Human-readable label for the intent
--session <id>      Group requests under a session id in the console
--key <value>       Placeholder key to write (default: anyray-placeholder)
--tools <ids>       Comma-separated subset of claude-code, codex, cursor, windsurf,
                    shell-env (default: all detected)
--dry-run           Show the plan, write nothing
--yes, -y           Skip the confirmation prompt (scripted / fleet rollout)
--force             Skip the gateway reachability check before writing
--revert            Undo a previous run
--help, -h          Show usage

Common workflows​

Preview before writing anything:

npx anyray-connect --gateway https://gw.yourorg.internal --dry-run

Connect only specific tools:

npx anyray-connect --gateway https://gw.yourorg.internal --tools claude-code,shell-env

Scripted fleet rollout (no prompt), with team attribution:

npx anyray-connect \
  --gateway https://gw.yourorg.internal \
  --user you@yourorg.com --team platform --yes

Undo everything it wrote:

npx anyray-connect --revert

After connecting​

Open a new shell (so the updated profile loads) or restart your editor, then use your tools exactly as before — only the base URL has changed. From here your requests flow through the gateway, get optimized, and are metered into the content-free spend store.

The Anyray console also ships a Connect page with these same on-ramp instructions, so your org can hand developers a single place to get pointed at the gateway.