Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Quick agent install

Paste one prompt into your coding agent and it runs the install for you.

What you need before you paste​

Have your Anyray Billing app deployment token ready. Open app.anyray.ai, run the setup wizard (or go to Settings → Deployments → New deployment), and copy the token that starts with adt_.

The adt_... token is required for usage metering and for the Billing app to show the deployment as connected. Do not confuse it with the console admin token from .env, provider API keys entered in the console, or user enrollment links created later from the Users page.

SSO blocked by your network?

If your network or security policy blocks the single sign-on redirect, use the "Sign in with email instead" link on the login page — it sends a one-time email code and skips the enterprise-IdP handoff.

After the agent finishes the install, use the console setup checklist: add provider keys, send a test request, then onboard users. Once SSO is configured, share the command under Users → SSO enrollment; it installs Connect, authenticates the developer, and configures every supported tool it detects without an admin-created invite.

Desktop apps​

anyray-connect covers local configurable surfaces: Claude Code CLI and its VS Code extension; the Codex app, CLI, and IDE extension; Cursor's local hooks/MCP and optional OpenAI override; OpenCode direct providers; JetBrains AI Assistant; Devin Desktop via its in-IDE ACP agents; Claude Desktop's third-party gateway mode; GitHub Copilot Chat in VS Code; the standalone GitHub Copilot CLI via its BYOK env contract; and shell/SDK env. The CLI automates supported, application-owned seams and prints exact vendor steps where a one-time enablement remains.

Connect uses application-owned configuration only: base URLs, Claude Desktop's Gateway mode, Codex's shared config, ACP registries, and VS Code's supported language-model-provider API. A normal run does not install a CA or change machine-wide DNS, NAT, or proxy settings.

When VS Code is attached to a remote host over Remote-SSH, a dev container, or a Codespace, run Connect from that window's integrated terminal so it configures the remote extension host — the side that renders Copilot Chat. A local run only reaches your laptop's VS Code; see GitHub Copilot for the full remote flow.

For Cursor Team with a native Claude/Opus model, keep Cursor's Team login and run:

anyray-connect https://gw.example.com --tools cursor \
  --user dev@example.com --yes

If the organization uses Anyray SSO enrollment, run anyray-connect --sso https://app.anyray.ai/sso/<tenantId> --tools cursor --yes instead. Cursor's own Team SSO session remains inside Cursor; Anyray SSO only mints the personal hook/MCP key.

This mode does not install an OpenAI base-URL override or an Anthropic API key. It installs the user-level Cursor hooks and Anyray retrieval MCP server. A recognized oversized local Shell result or MCP result can be reduced before it enters later model context; a realized reduction records a content-free hook-savings event. Shell command rewriting currently runs on macOS/Linux; MCP output handling remains available on every supported desktop OS. Native Claude/Opus inference itself remains on Cursor's service, so it does not produce a gateway inference trace and Anyray cannot rewrite that hidden request. User-level hooks are local-only; Cursor cloud agents do not load ~/.cursor/hooks.json.

If an earlier Connect run queued or applied the OpenAI BYOK route, the normal Team-mode run cancels the queued write and restores its journaled values. When Connect reports the restore as queued, fully quit Cursor and let the watcher finish before reopening it. Cursor watches hooks.json, but restart once so the MCP registration is loaded.

Cursor's separate BYOK/OpenAI override remains available through explicit --org for organizations that intentionally use an upstream provider API key. Cursor does not publish a managed-config contract for that app-state route, so Connect updates only the exact journaled cells it recognizes and fails closed on an unfamiliar shape. That API lane is not the Cursor Team Claude/Opus entitlement. Claude Desktop also publishes the third-party inference UI rather than a managed contract for its local config-library files. The macOS write is limited to verified Claude Desktop builds, is journaled, and fails closed to the UI on every other or unverifiable version.

Onboard the developer before a real Connect apply. The gateway requires the personal ark_… key minted by passwordless or SSO enrollment; Connect reuses a locally cached, unexpired key on later runs and never installs a placeholder-only configuration.

Managed flags are the bootstrap snapshot, not the long-term fleet authority. After enrollment, Connect pulls /connect/policy during sync and detached refresh. The server can correct the gateway routing origin, key-bound team attribution, and enabled tool set alongside shared skills. Enabled tools are applied when supported and installed; tools omitted from policy are never forcibly disabled.

Some first-party lanes expose no supported endpoint seam. Claude Desktop's first-party subscription stays direct on every platform. On verified macOS builds, however, the third-party Gateway lane can use the developer's Claude Code subscription credential through a local Keychain-backed helper; setup never reads it, and the helper never persists or logs it. Windows remains API-billed and fails closed when subscription is selected. OpenCode ChatGPT OAuth stays untouched; use the Codex app/CLI/IDE for that subscription, or an OpenCode API-key/Copilot provider. JetBrains Copilot stays untouched; use VS Code Copilot Chat or OpenCode for config-native Copilot subscription routing. The standalone GitHub Copilot CLI routes through its BYOK env contract, pointed at the gateway's Copilot carrier route with the developer's own seat token, so billing stays on the Copilot plan; Connect configures it in the default sweep whenever it can read a Copilot sign-in, holds a seat with no readable sign-in, and uses org API billing only under --org or with no seat on the machine.

For one developer, skip the paste with anyray-connect desktop --apply — on macOS this is automatic only for verified Claude Desktop builds; every other or unverifiable build receives the supported in-app flow without a write. On Windows it configures the machine directly (per-user, no admin). Fully quit and reopen Claude afterward. The supported macOS build uses the observed app state written by Configure Third-Party Inference → Apply locally, activates the selected API or Claude Code subscription-backed third-party profile, and journals the prior profile/mode so anyray-connect --revert can restore it; on Windows it writes HKCU\SOFTWARE\Policies\Claude and installs a key-free helper. Restart Claude after setup; later enrolled-key renewals are automatic. Connect leaves an existing machine-level HKLM policy unchanged. A normal npx run saves the stable Connect copy the helper needs; direct temporary-only runs stop before changing Claude. The first-party Desktop lane is never redirected.

Prefer the guided paste? Enable the Developer menu from the macOS menu bar at the top of the screen (not the in-app help panel): Help → Troubleshooting → Enable Developer Mode. Then run anyray-connect desktop claude — it prints the exact in-app gateway settings and the short-lived credential alone on stdout. Paste them under the menu bar's Developer → Configure third-party inference (the Developer menu at the top of the screen — not Settings → Developer, which is the Local MCP servers pane) and click Apply locally, then relaunch Claude. The artifact forms below are for fleets:

anyray-connect desktop --mobileconfig --gateway https://gw.example.com \
  --helper-path /usr/local/bin/anyray-credential-helper > claude-desktop.mobileconfig
anyray-connect desktop --reg --gateway https://gw.example.com \
  --helper-path "C:\Program Files\Anyray\anyray-credential-helper.cmd" > claude-desktop.reg

Those commands deliberately fail when --helper-path is omitted. Before deploying the artifact, put the standalone binary at /usr/local/bin/anyray-connect or C:\Program Files\Anyray\anyray-connect.exe, then install the matching helper on every endpoint:

sudo /usr/local/bin/anyray-connect desktop helper --write --platform posix \
  --bin /usr/local/bin/anyray-connect
& "C:\Program Files\Anyray\anyray-connect.exe" desktop helper --write `
  --platform windows --bin "C:\Program Files\Anyray\anyray-connect.exe"

desktop helper --print emits the wrapper alone for MDM packaging. The helper contains no static credential and invokes only the explicit durable binary. Each signed-in user still needs Connect enrollment; the helper resolves that user's current key at runtime. See Desktop apps for the complete contract.

Codex is the inverse: the Codex app, CLI, and IDE extension share ~/.codex/config.toml / $CODEX_HOME, so the existing Codex adapter reaches the app. If the app's model picker misses custom-provider models, pin the model with ANYRAY_CODEX_MODEL and re-run Connect. Connect also carries the top-level model_context_window and model_auto_compact_token_limit values as content-free provider headers. The gateway uses them to scale the optimizer's context budget, so a configured 1M session is not constrained by a fixed 190k ceiling.

Codex retrieval is automatic, but source-side tool-output trim is not. Its only replacement signal, decision: "block", rejects the nested tool promise after execution in code mode. That can make a successful shell, file-edit, or MCP side effect look failed and invite a duplicate retry. Connect does not install that unsafe carrier; apply and --revert remove the retired owned entry while preserving other hook configuration.

For fleets, generate the managed routing artifacts:

anyray-connect desktop codex --gateway https://gw.example.com \
  --helper-path /usr/local/bin/anyray-credential-helper > managed_config.toml
anyray-connect desktop codex --mobileconfig --gateway https://gw.example.com \
  --helper-path /usr/local/bin/anyray-credential-helper > codex.mobileconfig

For Windows Codex, pass the Windows .cmd helper path; Connect emits a cmd.exe command-auth invocation rather than asking Codex to spawn a batch file directly.

Custom-inference traffic routed with an Anyray gateway credential runs on the org-key/API lane, not the user's claude.ai seat. Cursor native Team/Opus is the local-hook exception described above: its inference stays on Cursor while supported local context can still be reduced. Cloud or remote sessions, including Claude web/Slack and Codex cloud/web tasks, run on provider infrastructure and cannot route through a local gateway.

Anyray install prompt
You are installing Anyray, a self-hosted AI-spend optimizer (gateway +
optimizer + observability console). Docs: https://docs.anyray.ai

## Step 1 — Ask the operator (do not guess)

1. Where should Anyray run? (this machine / a remote VM with SSH — EC2, GCP,
   etc. / somewhere else)
2. What hostname or IP will users reach it on?
3. Their Anyray Billing app deployment token (starts with `adt_`) — they get it at
   https://app.anyray.ai (setup wizard, or Settings → Deployments → New deployment). This is required
   for usage metering — every deployment connects to Anyray Billing app to report spend.

## Step 2 — Platform preparation (your job)

- Ensure the target machine has Docker Engine + Compose v2 and ~2 GB RAM free
  for a small install; size up only when trace/spend volume grows.
- Ensure ports 3000 (console) and 8787 (gateway API) are reachable from the
  org's network ONLY — e.g. a security group scoped to the office/VPN CIDR.
  NEVER open them to 0.0.0.0/0.
- If a DNS record is wanted, create it before installing and use it as <host>.

## Step 3 — Install (run exactly this; do not improvise)

On the target machine (or with DOCKER_HOST=ssh://user@<vm> from here):

```bash
git clone https://github.com/anyrayHQ/install anyray && cd anyray
./setup.sh --host <host> --connect <adt_token>
docker compose up -d
```

(If the gateway will be reached at a URL other than `http://<host>:8787` — e.g.
behind TLS or a load balancer — add `--gateway-url <url>` so the Billing app shows
users the right connect URL.)

Do NOT hand-assemble compose files, edit image tags, or generate secrets
yourself — `setup.sh` and the pinned artifacts are the only install path.

## Step 4 — Verify and hand off

```bash
docker compose ps                      # all services healthy/running
curl -fs http://<host>:8787/           # gateway answers
curl -fso /dev/null http://<host>:3000/anyray-login && echo console-ok
```

Report to the operator: the console URL (http://<host>:3000), where the admin
key lives (`.env`, `ANYRAY_ADMIN_TOKEN` — `setup.sh` printed it once), and that
the next step is the in-console setup (~3 min): connect a provider key, send a
test request, then onboard users from the **Users** page (the
single home for enrolling users — invite links, MDM, and SSO all live here). Use
API-key traffic for the routing test. Claude Code subscription pass-through can verify enrollment
and savings while keeping the user's first-party token instead of using provider routing; on a
verified macOS build, Claude Desktop can use the same subscription-backed Gateway contract.
Also tell them the deployment will appear as Connected at https://app.anyray.ai within a minute.

## Hard rules

- NEVER ask for, read, or handle provider API keys (OpenAI/Anthropic/etc.) —
  the operator enters them in the console themselves.
- NEVER expose ports 3000/8787 publicly.
- Content capture defaults to `encrypted` (ciphertext at rest). Leave it as the
  operator's choice — set `ANYRAY_CONTENT_MODE=off`, or deploy-gate `plaintext`
  with `ANYRAY_ALLOW_PLAINTEXT=true`, only if they ask; never silently change the mode.
- NEVER print the contents of `.env` into your conversation beyond confirming
  it exists. In particular ANYRAY_PSEUDONYM_SALT is privacy-critical and must
  never leave the machine — `setup.sh --connect` generates it locally.