Xray XHTTP VPN Orchestrator

Public, sanitized release package for the xray-xhttp-vpn-orchestrator skill.

This repository contains one visible orchestrator skill with internal worker modules and deterministic helper scripts for authorized Xray/VLESS/XHTTP VPN operations. It is built for cases where an AI agent must configure or audit VPN infrastructure without leaking secrets, inventing evidence, or applying live DNS/VPS changes too early.

Diagrams

Markdown versions:

• Skill architecture
• Server runtime flow
• Client artifacts flow

What This Skill Is

xray-xhttp-vpn-orchestrator is a workflow and automation skill for safe Xray/VLESS/XHTTP VPN work:

• it classifies a request as DNS, server build, deployment, client artifacts, split routing, diagnostics, or observability;
• it routes the work to internal worker modules under group/workers/*/WORKER.md;
• it asks the user to choose a safe endpoint-domain strategy before build work when the domain is missing or ambiguous;
• it generates deterministic server/client artifacts with scripts under scripts/;
• it blocks unsafe live mutation unless the user explicitly approves it and the matching gate is used;
• it keeps public documentation free of raw UUIDs, client links, tokens, private keys, and raw logs.

The skill is not a generic VPN product and not a subscription panel. It is an agent-side operating discipline plus scripts for people who already own or administer their VPS, DNS zone, and client devices.

Who It Helps

This is useful for:

• personal or small-team VPN operators who run Xray/VLESS/XHTTP on their own VPS;
• engineers who need repeatable nginx + Xray + DNS + client artifact workflows;
• agent users who want Codex/Claude/Gemini/etc. to help with VPN work without touching production blindly;
• anyone who needs per-device identity discipline instead of sharing one UUID across all devices.

It is probably too heavy if you only need to paste one VLESS URI into one app once.

What It Does

The current package can:

• validate endpoint inventory and split-routing JSON;
• choose and normalize endpoint-domain strategy: owned root domain, owned subdomain, or FreeDNS/shared-domain fallback;
• probe DNS authority and plan Cloudflare DNS records;
• build an Xray/VLESS/XHTTP server package from structured facts;
• generate one client artifact directory per physical device;
• generate a primary full Xray client JSON with split routing: clients/<device>/xray-client-full-split.json;
• generate fallback import links: clients/<device>/vless-uri.txt;
• generate reusable xray-outbound.json, sing-box-outbound.json, and clash-mihomo.yaml;
• validate client artifact manifests and static split-routing shape;
• fail closed in release checks unless a checksum-verified, pinned official Xray parser accepts the generated server config and every primary full-client JSON;
• perform dry-run or gated live SSH deployment to an authorized VPS;
• redact generated artifacts before anything is copied into public docs or a wiki.

Real device import/connect proof still requires device-side smoke tests in the target client apps. The pinned parser gate proves configuration acceptance only; it does not claim that a live VPN connection succeeds or that traffic selects the intended route.

Endpoint Domain Choice

Before DNS, server build, or client artifact work, the orchestrator can route missing or ambiguous domain requests to dns-endpoint-selector.

The selector produces an endpoint-domain-decision.json contract with:

• selected endpoint FQDN;
• strategy: owned root domain, owned subdomain, or FreeDNS fallback;
• provider/apply mode;
• downstream fields for server facts, SNI, nginx server_name, and client endpoint;
• risk warnings and required evidence.

The recommended path is a dedicated owned subdomain such as vpn.example.net. Root domains require explicit root/www/mail impact review. FreeDNS/shared-domain endpoints are fallback only: they may be useful when the user has no domain, but they carry reputation, availability, account-policy, and ownership-control risks. The package does not automate FreeDNS account creation, web-panel login, captcha handling, or HTML form scraping, and it must not store token-bearing FreeDNS update URLs.

Main Output Contract

For each device identity, the main artifact is:

clients/<identity_ref>/xray-client-full-split.json

It contains:

• endpoint address and port;
• UUID for exactly one physical device identity;
• VLESS + XHTTP transport settings;
• TLS/SNI/fingerprint/path/mode settings;
• DNS policy;
• RU/private direct routing rules;
• proxy as the first/default outbound for unmatched traffic; empty matcherless catch-all rules are rejected by Xray and by the bundled validators;
• local SOCKS/HTTP inbounds for Xray-family clients.

The fallback import artifact is:

clients/<identity_ref>/vless-uri.txt

This is useful for clients that import VLESS links more reliably than full JSON.

Repository Layout

xray-xhttp-vpn-orchestrator-public/
├── README.md
├── LICENSE
├── adapters/
│   ├── codex/
│   ├── claude-code/
│   ├── gemini/
│   ├── antigravity/
│   ├── vs-codium/
│   ├── qwen/
│   ├── zai-glm/
│   ├── kimi/
│   └── github-copilot/
├── docs/diagrams/
├── release/
└── xray-xhttp-vpn-orchestrator/
    ├── SKILL.md
    ├── group/workers/*/WORKER.md
    ├── scripts/
    ├── assets/examples/
    └── evals/

Only xray-xhttp-vpn-orchestrator/SKILL.md is the visible skill entrypoint. Worker files are internal modules and must not be installed as separate top-level skills.

Supported Targets

Target	Package support
Codex	Native single-skill container shape
Claude Code	Portable adapter instructions
Gemini	Portable adapter instructions
Antigravity	Portable adapter instructions
VS Codium	Portable adapter instructions
Qwen	Portable adapter instructions
Z.ai GLM	Portable adapter instructions
Kimi	Portable adapter instructions
GitHub Copilot	Portable repository instruction adapter

Target notes are in adapters/<target>/. Non-Codex targets are packaged as portable instructions until their native runtime loading is smoke-tested in the target environment.

CI/CD

GitHub Actions workflow: .github/workflows/ci.yml.

The CI pipeline runs on push, pull_request, and manual workflow_dispatch:

• Python 3.11, 3.12, and 3.13 unit tests;
• full release checks via scripts/run_all_checks.py;
• single-container package validation;
• FI quick-start build/export/validation smoke;
• repository sanitation checks;
• npm pack --dry-run.

Automated publishing/deployment is not configured. Release publication is manual by design so package or registry tokens are not stored in the repository or GitHub Actions secrets without an explicit release policy.

License

Apache License 2.0. See LICENSE.

Requirements

Python helper scripts intentionally use only the Python standard library. requirements.txt is present as an explicit dependency contract and currently contains no external packages.

python -m pip install -r requirements.txt

Optional external CLIs such as xray, sing-box, mihomo, ssh, scp, and gh are detected by the relevant scripts when needed; they are not Python package dependencies.

Quick Start With The Sanitized FI Example

The FI example intentionally contains public endpoint facts only. It does not contain real UUIDs, client links, tokens, private keys, or server logs.

From the public package root:

cd xray-xhttp-vpn-orchestrator
python3 scripts/generate_xray_build_package.py \
  --input assets/examples/fi-xhttp-443-new-users-build-input.json \
  --out /tmp/fi-xhttp-build \
  --generate-uuid

The command creates a private build package under /tmp/fi-xhttp-build. Because --generate-uuid creates real device UUID material, do not commit that output.

Generate per-device client artifacts:

python3 scripts/export_xray_artifacts.py \
  --input /tmp/fi-xhttp-build/client-export-input.json \
  --out /tmp/fi-xhttp-clients

Validate artifacts:

python3 scripts/validate_client_artifacts.py \
  /tmp/fi-xhttp-clients/client-artifacts.manifest.json \
  --output /tmp/fi-xhttp-clients/validation-report.json

python3 scripts/validate_split_routing.py \
  --input /tmp/fi-xhttp-clients/clients/phone-user-fi-example/xray-client-full-split.json \
  --output /tmp/fi-xhttp-clients/phone-user-split-routing.json

Plan deployment without changing the VPS:

python3 scripts/deploy_xray_xhttp_server.py \
  --package-dir /tmp/fi-xhttp-build \
  --host 203.0.113.10 \
  --user root \
  --output /tmp/fi-xhttp-build/deploy-dry-run.json

Live apply requires explicit operator approval and:

--apply --acknowledge-live-mutation

Safety Boundary

Generated build/client output is private and is not part of this repository. The release package is checked by sanitation tests before publication.

Verification

From inside xray-xhttp-vpn-orchestrator/:

python3 tests/test_xray_artifact_exporter.py
python3 scripts/run_all_checks.py --skill-path . --workspace /tmp/xray-xhttp-release-checks
python3 scripts/check_single_container_package.py .

Static validation is not the same as live client proof. Real production confidence requires:

• server-side xray run -test and nginx -t;
• live apply/rollback rehearsal on an authorized VPS;
• device import/connect smoke tests in the target apps;
• postflight traffic and stats evidence.

---

Xray XHTTP VPN Orchestrator — Русский

Это публичный очищенный пакет skill-а xray-xhttp-vpn-orchestrator.

Пакет содержит один видимый skill-оркестратор, внутренние worker-модули и набор детерминированных скриптов для разрешённой работы с Xray/VLESS/XHTTP VPN. Он нужен не для красивой демонстрации, а для практической работы: собрать конфиги, не потерять порядок действий, не засветить секреты и не применить опасные DNS/VPS изменения без явного подтверждения.

Что Это

xray-xhttp-vpn-orchestrator помогает агенту:

• понять тип задачи: DNS, сборка сервера, деплой, клиентские конфиги, split routing, диагностика или мониторинг;
• прочитать нужный внутренний worker из group/workers/*/WORKER.md;
• выбрать безопасную стратегию endpoint-домена, если домен отсутствует или неоднозначен;
• сгенерировать серверные и клиентские артефакты через scripts/;
• не менять DNS/VPS/router/nginx/Xray без явного подтверждения;
• не записывать в публичные документы UUID, client links, токены, приватные ключи и сырые логи.

Это не VPN-панель и не сервис подписок. Это рабочий skill для владельца VPS/DNS/клиентов, который хочет, чтобы агент действовал аккуратно и проверяемо.

Кому Пригодится

Пакет полезен, если вы:

• поднимаете Xray/VLESS/XHTTP на своих VPS;
• хотите повторяемую схему nginx + Xray + DNS + client artifacts;
• используете Codex/Claude/Gemini/другого агента для инфраструктурных задач;
• хотите отдельный UUID/email на каждое физическое устройство, без общей UUID на все клиенты.

Что Он Делает

Текущая версия умеет:

• валидировать inventory endpoint-ов и split-routing JSON;
• выбирать стратегию endpoint-домена: свой root domain, поддомен своего домена или FreeDNS/shared-domain fallback;
• проверять DNS authority и планировать Cloudflare DNS records;
• собирать пакет Xray/VLESS/XHTTP сервера из структурированных facts;
• генерировать отдельную папку артефактов на каждое устройство;
• генерировать основной полный Xray JSON со split routing: clients/<device>/xray-client-full-split.json;
• генерировать fallback-ссылку: clients/<device>/vless-uri.txt;
• генерировать xray-outbound.json, sing-box-outbound.json, clash-mihomo.yaml;
• валидировать manifest клиентских артефактов и форму split-routing;
• делать dry-run или gated live deploy на разрешённый VPS по SSH;
• очищать артефакты перед публикацией в wiki/docs.

Реальная проверка импорта и подключения всё равно делается на физических клиентах: v2rayN, v2rayNG, Nekoray, Shadowrocket, Streisand, Happ и других.

Выбор Endpoint-Домена

Если endpoint-домен не выбран, skill сначала ведёт пользователя через dns-endpoint-selector, а не сразу собирает сервер или клиентские конфиги.

Worker формирует endpoint-domain-decision.json:

• выбранный FQDN;
• стратегия: root-домен, поддомен своего домена или FreeDNS fallback;
• provider/apply mode;
• поля для server facts, SNI, nginx server_name и client endpoint;
• предупреждения о рисках и список evidence.

Практичный default — отдельный поддомен своего домена, например vpn.example.net. Root-домен требует отдельной проверки влияния на root/www/mail. FreeDNS/shared-domain — только fallback, если своего домена нет: там выше риски репутации, доступности, политики аккаунта и контроля имени. Пакет не автоматизирует создание FreeDNS-аккаунта, вход в web-panel, captcha, HTML-form scraping и не должен хранить FreeDNS update URL/token.

Главный Итоговый Артефакт

Для каждого устройства главный файл:

clients/<identity_ref>/xray-client-full-split.json

В нём есть:

• endpoint и порт;
• UUID для конкретного физического устройства;
• VLESS + XHTTP transport;
• TLS/SNI/fingerprint/path/mode;
• DNS policy;
• RU/private direct rules;
• proxy как первый/default outbound для unmatched traffic; пустое catch-all правило без matcher запрещено;
• локальные SOCKS/HTTP inbounds для Xray-family клиентов.

Fallback-файл:

clients/<identity_ref>/vless-uri.txt

Он нужен для клиентов, которым проще импортировать VLESS-ссылку, чем полный JSON.

Release-check использует официальный Xray с точной версией и SHA-256 из references/xray-compatibility-matrix.json. Это подтверждает parser validity, но не live-connect, фактический выбор маршрута или импорт в физическом клиенте.

Как Пользоваться

Для Codex установите папку xray-xhttp-vpn-orchestrator/ как один skill. Worker-файлы внутри group/workers/ не надо устанавливать отдельно.

Для других провайдеров используйте adapter-файлы:

• adapters/claude-code/CLAUDE.md
• adapters/gemini/GEMINI.md
• adapters/antigravity/AGENTS.md
• adapters/vs-codium/AGENTS.md
• adapters/qwen/QWEN.md
• adapters/zai-glm/GLM.md
• adapters/kimi/KIMI.md
• adapters/github-copilot/copilot-instructions.md

Лицензия

Apache License 2.0. См. LICENSE.

CI/CD

GitHub Actions workflow лежит здесь: .github/workflows/ci.yml.

Пайплайн запускается на push, pull_request и вручную через workflow_dispatch; он проверяет Python 3.11/3.12/3.13, release checks, FI quick-start smoke, sanitation и npm pack --dry-run.

Автоматическая публикация/деплой не настроены. Релизы публикуются вручную, чтобы не хранить package/registry tokens в репозитории или GitHub Actions secrets без отдельной release-policy.

Зависимости

Python-скрипты намеренно используют только стандартную библиотеку Python. requirements.txt добавлен как явный контракт зависимостей; внешних Python-пакетов сейчас нет.

python -m pip install -r requirements.txt

Быстрый пример на очищенных FI facts:

cd xray-xhttp-vpn-orchestrator
python3 scripts/generate_xray_build_package.py \
  --input assets/examples/fi-xhttp-443-new-users-build-input.json \
  --out /tmp/fi-xhttp-build \
  --generate-uuid

python3 scripts/export_xray_artifacts.py \
  --input /tmp/fi-xhttp-build/client-export-input.json \
  --out /tmp/fi-xhttp-clients

Важно: результат в /tmp/fi-xhttp-build и /tmp/fi-xhttp-clients уже содержит приватные UUID/client artifacts. Его нельзя коммитить в публичный репозиторий.

Проверка:

python3 scripts/validate_client_artifacts.py \
  /tmp/fi-xhttp-clients/client-artifacts.manifest.json \
  --output /tmp/fi-xhttp-clients/validation-report.json

python3 scripts/validate_split_routing.py \
  --input /tmp/fi-xhttp-clients/clients/phone-user-fi-example/xray-client-full-split.json \
  --output /tmp/fi-xhttp-clients/phone-user-split-routing.json

Граница Безопасности

Сгенерированные build/client outputs приватные и не входят в этот репозиторий. Перед публикацией пакет проверяется sanitation-тестами.