Skip to content

Enterprise RU

Pavel Erokhin edited this page Nov 20, 2026 · 3 revisions

English version

В корпоративной сети ctxray работает так же, как на ноутбуке: за прокси, со своими CA-сертификатами, через LLM-шлюз, из внутреннего npm-реестра или вовсе без сети. Здесь описано, как настроить каждый из этих случаев и что ctxray обещает насчёт ваших данных.

Начните с ctxray doctor

ctxray doctor проверяет, что нужно слоям L4 и выше на этой машине: git, сеть, кеш и закреплённые харнессы. Запускайте его первым делом на каждом новом раннере и после каждого изменения сети:

$ ctxray doctor --lang en

 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

Ошибка завершает команду с кодом 4, предупреждение только говорит, что может пойти не так. Пароль прокси в выводе не появляется: вывод попадает в логи CI.

Раздел Что проверяет
System git (L4 и выше копируют проект через него), Node.js (без него не стартуют MCP-серверы на Node), настройки администратора в /etc/claude-code, /etc/codex или их аналогах на macOS и Windows, которые ни один прогон не изолирует, и песочницу
Network прокси, записи NO_PROXY, которые Bun читает не так, как curl, каждый CA-файл, npm-реестр и отвечает ли он
Harnesses доступен ли кеш на запись, кеши только для чтения, ctxray.lock против конфига и каждый закреплённый харнесс на этой платформе

LLM-шлюзы и ключи

К провайдеру модели обращаются только слои L6 и L7 с --backend real, точный подсчёт токенов (exactTokens), ctxray gen-prompts и ctxray calibrate. Всё остальное остаётся на машине.

По умолчанию ctxray отправляет каждый запрос в API самого провайдера. Чтобы ходить через корпоративный шлюз, укажите его один раз в конфиге или в окружении — окружение важнее:

export default defineConfig({
  upstream: "https://llm-gateway.corp.example",
});
export CTXRAY_UPSTREAM=https://llm-gateway.corp.example

ctxray дописывает к этому URL путь харнесса без изменений: /v1/messages для Anthropic, /v1/responses или /v1/chat/completions для OpenAI, /v1beta/models/… для Gemini. Значит, шлюз должен отдавать API каждого провайдера под одним базовым URL.

Настоящего ключа у харнесса никогда нет. ctxray даёт ему фиктивный ключ, а прокси подставляет настоящий на выходе:

Переменная Куда уходит Как
CTXRAY_UPSTREAM_KEY во все протоколы, раньше ключей провайдеров в заголовке своего протокола
ANTHROPIC_API_KEY Anthropic Messages x-api-key
OPENAI_API_KEY OpenAI Responses и Chat Completions Authorization: Bearer
GEMINI_API_KEY Gemini x-goog-api-key
CLAUDE_CODE_OAUTH_TOKEN Anthropic, если ни один ключ выше не задан Authorization: Bearer с OAuth-бетой

CLAUDE_CODE_OAUTH_TOKEN — это токен, который печатает claude setup-token, для команд, у которых Claude Code работает по подписке. Если ключа нет совсем, ctxray его не отправляет, и upstream отвечает 401 своими словами.

Прокси

ctxray читает привычные переменные, сначала в нижнем регистре, как Bun: HTTPS_PROXY, HTTP_PROXY и NO_PROXY. Конфиг их перекрывает: он написан для ctxray, а переменные — для всех программ сразу:

export default defineConfig({
  network: {
    proxy: "http://proxy.corp.example:3128",
    noProxy: [".corp.example", "localhost"],
  },
});

Пишите записи NO_PROXY так, как их читает Bun. Домен с точкой в начале, .corp.example, покрывает свои поддомены — там, где пользователи curl часто пишут *.corp.example. Диапазоны CIDR вроде 10.0.0.0/8 не работают: перечислите хосты. ctxray doctor предупреждает об обеих формах. Ещё он предупреждает, когда задан только HTTP_PROXY: ctxray и HTTPS отправляет через него, а вот запущенные им MCP-серверы ходят мимо.

Через этот прокси идут запросы самого ctxray: установка харнессов, реестр, upstream модели. Запущенные им харнессы выходят в сеть только через прокси ctxray (Изоляция). MCP-серверы, запущенные за ctxray, получают ваши настоящие HTTPS_PROXY, HTTP_PROXY и NO_PROXY.

CA-сертификаты

Прокси, который вскрывает TLS, требует ваш корневой сертификат. Дополнительные CA-файлы ctxray берёт из трёх мест:

Где Что
network.ca в конфиге PEM-файлы, пути относительно конфига, который их называет
NODE_EXTRA_CA_CERTS один PEM-файл, добавляется к файлам из конфига
ca и cafile в .npmrc для реестра (ниже)

network.systemCa: true или NODE_USE_SYSTEM_CA=1 заставляют ctxray доверять ещё и системному хранилищу сертификатов. SSL_CERT_FILE не читается.

export default defineConfig({
  network: {
    ca: ["./certs/corp-root.pem"],
    systemCa: true,
  },
});

MCP-серверы, запущенные за ctxray, получают те же сертификаты через NODE_EXTRA_CA_CERTS, а если файлов несколько, они сливаются в один PEM. ctxray doctor выдаёт ошибку на CA-файл, которого нет или в котором нет PEM-сертификата.

Внутренние npm-реестры

ctxray ставит харнессы из npm-пакетов. Реестр он выбирает так же, как npm, и побеждает первое совпадение:

  1. network.registry в конфиге
  2. реестр scope в .npmrc, например @anthropic-ai:registry=…
  3. NPM_CONFIG_REGISTRY, npm_config_registry или BUN_CONFIG_REGISTRY
  4. registry= в .npmrc
  5. https://registry.npmjs.org/

ctxray читает ваш пользовательский .npmrc ($NPM_CONFIG_USERCONFIG или ~/.npmrc), а потом .npmrc проекта рядом с ctxray.lock, который главнее. ${VAR} в значении берётся из окружения. Учётные данные уходят только в тот реестр, для которого предназначены, по самому длинному подходящему префиксу //host/path/::

registry=https://npm.corp.example/
//npm.corp.example/:_authToken=${NPM_TOKEN}
cafile=./certs/corp-root.pem

_authToken уходит как bearer-токен, _auth или username с _password — как basic-аутентификация. ca и cafile ctxray читает сам, потому что за прокси Bun теряет сертификаты из .npmrc. Относительный cafile считается от своего .npmrc.

ctxray обращается к реестру, только когда закреплённого харнесса нет в кеше. Исключение — локальная сборка Cursor CLI: она приходит с downloads.cursor.com, а не из npm, поэтому зеркалируйте и этот хост или заносите сборку через harness pack.

Офлайн и изолированные сети

offline: true в конфиге или CTXRAY_OFFLINE=1 оставляют всё на машине. ctxray не ставит харнессы из сети и подсказывает, как занести их иначе. Токены считаются только локально, с оценкой. ctxray test --backend real, ctxray gen-prompts и ctxray calibrate останавливаются, не начав, с кодом выхода 4.

Сборки харнессов переходят воздушный зазор архивом из ctxray harness pack или внутри образа раннера из harnesses.Dockerfile. Сам ctxray приходит из вашего зеркала. Модели доступны через ваш шлюз. С offline: true работают L1–L5, L6 и L7 идут на replay или mock, а команды, которым нужна сеть, останавливаются с кодом 4.

Слоям L1–L5 сеть не нужна вовсе, поэтому офлайн они работают так же, как онлайн. L6 и L7 по-прежнему работают с --backend replay на записанных ответах или с mock. Корпоративному шлюзу внутри закрытой сети offline не нужен: укажите его в upstream, как показано в разделе LLM-шлюзы и ключи.

Занести харнессы в закрытую сеть можно тремя способами.

Архив. На машине с интернетом упакуйте сборки из ctxray.lock под все платформы ваших раннеров. Перенесите архив внутрь и установите из него. ctxray сверяет каждую сборку с integrity из ctxray.lock, как при скачивании:

# снаружи
ctxray harness pack --platform linux-x64-glibc,darwin-arm64 -o ctxray-harnesses.tar
# внутри
ctxray harness install --from ctxray-harnesses.tar

Общий кеш только для чтения. CTXRAY_CACHE_DIRS перечисляет несколько папок кеша через : (на Windows — ;). ctxray ищет во всех, а новые установки принимает первая доступная на запись. Положите один кеш на NFS или в образ раннера, и каждый job будет читать из него без копирования:

export CTXRAY_CACHE_DIRS="$HOME/.cache/ctxray:/mnt/nfs/ctxray"

Слой только для чтения ctxray никогда не чистит, а ctxray doctor показывает каждый такой слой. Устройство кеша описано на странице Harnesses.

Образ раннера. harnesses.Dockerfile из релиза собирает образ с харнессами внутри (CI Integration).

Для самого ctxray каждый архив релиза — офлайн-комплект: исполняемый файл, JSON Schema, шаблон GitLab, harnesses.Dockerfile и плагин для Claude Code (Getting Started).

Зеркало релизов ctxray

install.sh и install.ps1 скачивают из GitHub Releases. CTXRAY_DOWNLOAD_BASE направляет их на ваше зеркало, которое повторяет структуру GitHub:

<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 sh

Зеркалируйте вместе с архивами и SHA256SUMS: скрипт сверяет с ним каждую загрузку. GitHub Action принимает ту же базу во входном параметре download-base:

- uses: MairwunNx/ctxray-action@v0
  with:
    download-base: https://mirror.corp.example/ctxray

npm-пакеты приходят через ваш npm-прокси, как любые другие: @mairwunnx/ctxray и пакет платформы, от которого он зависит, например @mairwunnx/ctxray-linux-x64. Образы с ghcr.io/mairwunnx/ctxray переносятся в ваш реестр контейнеров, а CTXRAY_IMAGE направляет на них шаблон GitLab.

Один конфиг на всю компанию

extends строит конфиг проекта поверх других: путей или npm-пакетов из вашего реестра. Опубликуйте лимиты токенов, запрещённые MCP-серверы, шлюз и CA-файл один раз, в виде пакета:

// @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}/] },
});
// ctxray.config.ts проекта
import { defineConfig } from "@mairwunnx/ctxray";

export default defineConfig({
  extends: "@acme/ctxray-config",
  harnesses: { "claude-code": {}, codex: {} },
});

ctxray находит пакет в node_modules проекта, поэтому поставьте его как dev-зависимость. Путь к CA в пакете остаётся относительным пакету. Проект может поправить унаследованную политику по её id, например её строгость, но убрать шаблоны редактирования не может. Правила слияния — на странице Configuration, проверки — на странице Policies.

Что никогда не покидает машину

ctxray никуда не отправляет данные о вас. Нет ни телеметрии, ни проверки обновлений, ни отчётов о сбоях. Он обращается только к настроенному вами реестру, когда нужно поставить харнесс, и к upstream модели — в прогонах, которые спрашивают настоящую модель.

Секреты и персональные данные скрываются до того, как что-то попадёт на диск. ctxray заменяет API-ключи, токены, приватные ключи, email, номера телефонов и карт метками вида ⟦redacted:anthropic-key⟧ по своим шаблонам и правилам gitleaks, плюс шаблонам, которые ваш конфиг добавляет в redact.patterns. Это касается вывода в консоль, каждого отчёта, трейсов, кассет, и логов MCP. Шаблоны перечислены на странице Reporters and Reports.

  • Трейсы запросов харнесса лежат во временной папке системы, и ctxray удаляет их в конце прогона, если только не упал тест уровня L4 и выше.
  • В настоящем прогоне запрос харнесса уходит в ваш upstream таким, каким его написал харнесс: это и есть обращение к модели.

Бюджеты

Прогон с настоящей моделью перестаёт отправлять запросы, когда достигает бюджета. Тесты, которые начинаются после этого, пропускаются с причиной «бюджет исчерпан».

Где Что
budget.usd в конфиге сколько долларов США может потратить прогон
budget.tokens в конфиге сколько токенов может израсходовать прогон
CTXRAY_BUDGET_USD доллары, поверх конфига
--budget <usd> доллары, на один запуск ctxray test

Модели, которые ctxray запускает по умолчанию, у него уже с ценами. Для модели, которую шлюз отдаёт под другим именем, добавьте цену в prices в конфиге (Configuration). Модель, которую не удалось оценить, отчёт называет отдельно.

Изоляция

Начиная с L4, ctxray запускает настоящий харнесс. Он никогда не делает этого в вашем рабочем дереве или с вашей домашней папкой:

  • Копия проекта. Харнесс работает на временной копии репозитория вместе с вашими незакоммиченными изменениями. Свои метки ctxray пишет только в копию.
  • Изолированный HOME. HOME, TMPDIR и папки XDG_* указывают в собственную папку прогона. Харнесс не видит ~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, ~/.cursor и связку ключей macOS. Ваши собственные правила и MCP-серверы попадают в прогон только с userScope: "inherit".
  • Сторож исходящих соединений. HTTPS_PROXY, HTTP_PROXY и ALL_PROXY харнесса указывают на сторожа, который отклоняет и запоминает каждое соединение. Трафик к модели может попасть только в прокси ctxray, а тест падает, если харнесс пытался выйти мимо него.
  • Телеметрия выключена. ctxray запускает каждый харнесс с выключенной телеметрией и проверкой обновлений — насколько харнесс это позволяет.

Захват шаг за шагом разобран на странице Harnesses, песочница — на странице CI Integration.

Clone this wiki locally