xray-xhttp-vpn-orchestrator

KO | EN

gitlite — search

#javascript #react #ai #llm #golang #android #rust #nodejs #java #windows #kubernetes #security #mcp #open-source

xray-xhttp-vpn-orchestrator

(★ 10)

Sanitized public skill package for Xray/VLESS/XHTTP VPN orchestration

xray-xhttp-vpn-orchestrator Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Xray XHTTP VPN Orchestrator

[![CI](https://github.com/sergekostenchuk/xray-xhttp-vpn-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/sergekostenchuk/xray-xhttp-vpn-orchestrator/actions/workflows/ci.yml)

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

![Skill architecture](https://raw.githubusercontent.com/sergekostenchuk/xray-xhttp-vpn-orchestrator/main/docs/diagrams/images/01-skill-architecture.svg)

![Server runtime flow](https://raw.githubusercontent.com/sergekostenchuk/xray-xhttp-vpn-orchestrator/main/docs/diagrams/images/02-server-runtime-flow.svg)

![Client artifacts flow](https://raw.githubusercontent.com/sergekostenchuk/xray-xhttp-vpn-orchestrator/main/docs/diagrams/images/03-client-artifacts-flow.svg)

Markdown versions:

- [Skill architecture](docs/diagrams/01-skill-architecture.md)
- [Server runtime flow](docs/diagrams/02-server-runtime-flow.md)
- [Client artifacts flow](docs/diagrams/03-client-artifacts-flow.md)

## 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:

```text
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:

```text
clients/<identity_ref>/vless-uri.txt
```

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

## Repository Layout

```text
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`](.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](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.

```bash
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:

```bash
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:

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

Validate artifacts:

```bash
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:

```bash
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:

```text
--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/`:

```bash
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.

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

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

```text
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-файл:

```text
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](LICENSE).

## CI/CD

GitHub Actions workflow лежит здесь: [`.github/workflows/ci.yml`](.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-пакетов сейчас нет.

```bash
python -m pip install -r requirements.txt
```

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

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. Его нельзя коммитить в публичный репозиторий.

Проверка:

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

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

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

xray-xhttp-vpn-orchestrator

xray-xhttp-vpn-orchestrator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

xray-xhttp-vpn-orchestrator

xray-xhttp-vpn-orchestrator Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README