Repository navigation
Enterprise
ctxray runs inside a corporate network as it runs on a laptop: behind a proxy, with your own CA certificates, through an LLM gateway, from an internal npm registry, or with no network at all. This page shows how to set each of them up and what ctxray promises about your data.
ctxray doctor checks what L4 and up need on this machine: git, the network, the cache, and the pinned harnesses. Run it first on every new runner and after every network change:
$ ctxray doctor
System
· ctxray 0.1.0 on linux-x64-glibc
✓ git 2.54.0
✓ Node.js 26.13.1
· No sandbox on this system: run L4 and up in a container, as CI does
Network
✓ Proxy http://***@proxy.corp.example:3128/
! NO_PROXY entry “*.corp.example” doesn't work in Bun as in curl: write “.corp.example”
✓ CA certificates from /etc/ssl/corp/root.pem
✓ npm registry https://npm.corp.example/
✓ The registry answers (200)
Harnesses
✓ Cache /home/ci/.cache/ctxray: 2 builds, 512 MB
✓ Lockfile ctxray.lock
✓ claude-code 2.1.325 installed
✓ codex 0.169.0 installed
1 warning
An error exits with code 4, a warning only says what may go wrong. The proxy's password never shows, because the output lands in CI logs.
| Section | What it checks |
|---|---|
| System | git (L4 and up copy the project with it), Node.js (MCP servers on Node need it), settings an administrator put in /etc/claude-code, /etc/codex, or their macOS and Windows twins that no run can isolate, and the sandbox |
| Network | the proxy, NO_PROXY entries Bun reads differently from curl, each CA file, the npm registry and whether it answers |
| Harnesses | whether the cache is writable, read-only cache layers, ctxray.lock against the config, and each pinned harness on this platform |
Only layers L6 and L7 with --backend real, exact token counts (exactTokens), ctxray gen-prompts, and ctxray calibrate talk to a model provider. Everything else stays on the machine.
By default ctxray sends each request to the provider's own API. To go through a corporate gateway, name it once in the config or in the environment, which wins:
export default defineConfig({
upstream: "https://llm-gateway.corp.example",
});export CTXRAY_UPSTREAM=https://llm-gateway.corp.examplectxray appends the harness's own path to that URL unchanged: /v1/messages for Anthropic, /v1/responses or /v1/chat/completions for OpenAI, /v1beta/models/… for Gemini. So the gateway must serve each provider's API under one base URL.
The harness never holds a real key. ctxray gives it a dummy key, and its proxy swaps the key in on the way out:
| Variable | Sent to | As |
|---|---|---|
CTXRAY_UPSTREAM_KEY |
every protocol, ahead of the provider keys | each protocol's own header |
ANTHROPIC_API_KEY |
Anthropic Messages | x-api-key |
OPENAI_API_KEY |
OpenAI Responses and Chat Completions | Authorization: Bearer |
GEMINI_API_KEY |
Gemini | x-goog-api-key |
CLAUDE_CODE_OAUTH_TOKEN |
Anthropic, when no key above is set |
Authorization: Bearer with the OAuth beta |
CLAUDE_CODE_OAUTH_TOKEN is the token claude setup-token prints, for teams that run Claude Code on a subscription. With no key at all, ctxray sends none, and the upstream answers 401 in its own words.
ctxray reads the usual variables, lower case first, as Bun does: HTTPS_PROXY, HTTP_PROXY, and NO_PROXY. The config overrides them, because it's written for ctxray and they're written for everything:
export default defineConfig({
network: {
proxy: "http://proxy.corp.example:3128",
noProxy: [".corp.example", "localhost"],
},
});Write NO_PROXY entries the way Bun reads them. A domain with a leading dot, .corp.example, covers its subdomains, where curl users often write *.corp.example. CIDR ranges like 10.0.0.0/8 don't work: list the hosts. ctxray doctor warns about both forms. It also warns when only HTTP_PROXY is set: ctxray sends HTTPS through it too, but the MCP servers it starts go past it.
ctxray's own requests go through this proxy: harness installs, the registry, the model upstream. The harnesses it launches reach the network only through ctxray's proxy (Isolation). MCP servers launched behind ctxray get your real HTTPS_PROXY, HTTP_PROXY, and NO_PROXY.
A proxy that inspects TLS needs your root certificate. ctxray takes extra CA files from three places:
| Where | What |
|---|---|
network.ca in the config |
PEM files, relative to the config that names them |
NODE_EXTRA_CA_CERTS |
one PEM file, added to the config's |
ca and cafile in .npmrc
|
used for the registry (below) |
network.systemCa: true, or NODE_USE_SYSTEM_CA=1, makes ctxray trust the system's certificate store as well. SSL_CERT_FILE isn't read.
export default defineConfig({
network: {
ca: ["./certs/corp-root.pem"],
systemCa: true,
},
});MCP servers launched behind ctxray get the same certificates through NODE_EXTRA_CA_CERTS, merged into one PEM file when there are several. ctxray doctor fails on a CA file that's missing or holds no PEM certificate.
ctxray installs harnesses from npm packages. It reads the registry the way npm does, and the first match wins:
-
network.registryin the config - a scope's registry in
.npmrc, like@anthropic-ai:registry=… -
NPM_CONFIG_REGISTRY,npm_config_registry, orBUN_CONFIG_REGISTRY -
registry=in.npmrc https://registry.npmjs.org/
ctxray reads your user .npmrc ($NPM_CONFIG_USERCONFIG, or ~/.npmrc) and then the project's .npmrc next to ctxray.lock, which wins. ${VAR} in a value reads the environment. Credentials go only to the registry they're meant for, by the longest matching //host/path/: prefix:
registry=https://npm.corp.example/
//npm.corp.example/:_authToken=${NPM_TOKEN}
cafile=./certs/corp-root.pem_authToken goes as a bearer token, _auth or username with _password as basic authentication. ctxray reads ca and cafile itself, because Bun drops .npmrc certificates behind a proxy. A relative cafile is relative to its .npmrc.
ctxray touches the registry only when a pinned harness is missing from the cache. Cursor CLI's local build is the exception: it comes from downloads.cursor.com, not from npm, so mirror that host too or bring the build in with harness pack.
offline: true in the config, or CTXRAY_OFFLINE=1, keeps everything on the machine. ctxray installs no harness from the network and explains how to get them in another way. Token counts stay local estimates. ctxray test --backend real, ctxray gen-prompts, and ctxray calibrate stop before they start, with exit code 4.
L1–L5 need no network at all, so they run offline as they do online. L6 and L7 still run with --backend replay on recorded answers, or with mock. A corporate gateway inside your closed network needs no offline: point upstream at it, as LLM gateways and keys shows.
Three ways bring the harnesses into a closed network:
An archive. On a machine with internet, pack the builds ctxray.lock pins, for every platform your runners use. Carry the archive in, and install from it. ctxray checks each build against the integrity in ctxray.lock, as it would for a download:
# outside
ctxray harness pack --platform linux-x64-glibc,darwin-arm64 -o ctxray-harnesses.tar
# inside
ctxray harness install --from ctxray-harnesses.tarA shared read-only cache. CTXRAY_CACHE_DIRS lists several cache folders, separated by : (; on Windows). ctxray searches all of them, and the first writable one takes new installs. Put one cache on NFS or into the runner image, and every job reads from it without copying:
export CTXRAY_CACHE_DIRS="$HOME/.cache/ctxray:/mnt/nfs/ctxray"ctxray never prunes a read-only layer, and ctxray doctor lists each one. Harnesses describes the cache layout.
A runner image. harnesses.Dockerfile from the release builds an image with the harnesses inside (CI Integration).
For ctxray itself, each release archive is an offline bundle with the executable, the JSON Schemas, the GitLab template, harnesses.Dockerfile, and the Claude Code plugin (Getting Started).
install.sh and install.ps1 download from GitHub Releases. CTXRAY_DOWNLOAD_BASE points them at your mirror, which keeps GitHub's layout:
<base>/latest/download/<asset>
<base>/download/v<version>/<asset>
curl -fsSL https://mirror.corp.example/ctxray/latest/download/install.sh \
| CTXRAY_DOWNLOAD_BASE=https://mirror.corp.example/ctxray shMirror SHA256SUMS along with the archives: the script checks each download against it. The GitHub Action takes the same base as its download-base input:
- uses: MairwunNx/ctxray-action@v0
with:
download-base: https://mirror.corp.example/ctxrayThe npm packages come through your npm proxy like any other package: @mairwunnx/ctxray and the platform package it depends on, such as @mairwunnx/ctxray-linux-x64. The images on ghcr.io/mairwunnx/ctxray go to your container registry, and CTXRAY_IMAGE points the GitLab template at them.
extends builds a project's config on top of others: paths, or npm packages from your registry. Publish token limits, banned MCP servers, the gateway, and the CA file once, as a package:
// @acme/ctxray-config, index.ts
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
upstream: "https://llm-gateway.corp.example",
network: { ca: ["./corp-root.pem"] },
policies: [
{ id: "context-budget", maxTokens: { total: 25000 } },
{ id: "no-public-mcp", denyMcp: ["filesystem"] },
],
redact: { patterns: [/ACME-[0-9]{6}/] },
});// a project's ctxray.config.ts
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
extends: "@acme/ctxray-config",
harnesses: { "claude-code": {}, codex: {} },
});ctxray resolves the package from the project's node_modules, so install it as a dev dependency. A CA path in the package stays relative to the package. A project can adjust an inherited policy by its id, like its severity, but it can't drop redaction patterns. Configuration has the merge rules, and Policies the checks.
ctxray sends nothing about you anywhere. There's no telemetry, no update check, and no crash report. It talks only to the registry you configured, when a harness needs installing, and to the model upstream, in the runs that ask a real model.
Secrets and personal data are hidden before anything reaches the disk. ctxray replaces API keys, tokens, private keys, emails, phone numbers, and card numbers with markers like ⟦redacted:anthropic-key⟧, using its own patterns and gitleaks' rules, plus the patterns your config adds under redact.patterns. That covers the console output, every report, traces, cassettes, and MCP logs. Reporters and Reports lists the patterns.
- Traces of the harness's requests live in the system's temporary folder, and ctxray deletes them at the end of the run unless a test from L4 up failed.
- In a real run, the harness's request goes to your upstream as the harness wrote it: that's the model call itself.
A run against a real model stops sending once it reaches its budget. Tests that start after that are skipped with the reason “budget spent”.
| Where | What |
|---|---|
budget.usd in the config |
US dollars a run may spend |
budget.tokens in the config |
tokens a run may use |
CTXRAY_BUDGET_USD |
dollars, over the config |
--budget <usd> |
dollars, for one run of ctxray test
|
ctxray prices the models it runs by default. For a model your gateway serves under another name, add its price under prices in the config (Configuration). The report names any model it couldn't price.
From L4 up, ctxray launches the real harness. It never does so in your working tree or with your home folder:
- A project copy. The harness works on a temporary copy of the repository, with your uncommitted changes. ctxray writes its markers only into the copy.
-
An isolated home.
HOME,TMPDIR, and theXDG_*folders point into the run's own folder. The harness never sees~/.claude,~/.codex,~/.gemini,~/.config/opencode,~/.cursor, or the macOS keychain. Your own rules and MCP servers join the run only withuserScope: "inherit". -
An egress guard. The harness's
HTTPS_PROXY,HTTP_PROXY, andALL_PROXYpoint at a guard that refuses every connection and remembers it. Model traffic can reach ctxray's proxy alone, and a test fails when a harness tried to go past it. - Telemetry off. ctxray launches each harness with its telemetry and update checks turned off, as far as the harness allows.
Harnesses walks through a capture step by step, and CI Integration covers the sandbox.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие