Tracegate 2 is an Xray-centric control plane, node-agent and Telegram bot stack for a privacy gateway built around a primary Transit node and an optional Entry -> Transit chain.

The repository contains the public control logic, bundle templates, bot UX, observability hooks and host deployment contract. Private packet camouflage, zapret2 policies, MTProto secrets and local overlay files stay outside Git and are consumed through explicit runtime handoff surfaces.

Release notes live in CHANGELOG.md.

• issues VLESS, Hysteria2 and persistent Telegram Proxy access through a Telegram bot
• stores users, devices, connections, revisions and admin state in a central control plane
• delivers runtime changes to node agents through an outbox + dispatcher pipeline
• keeps Xray hot while ordinary config issuance changes only users, not the full runtime
• renders public bundles from repo templates and applies private overlays only on the target host
• exposes optional Prometheus + Grafana observability with bot-delivered Grafana access
• supports Transit-only rollout and Transit node replacement as first-class operational paths

• V1: direct VLESS + REALITY on Transit
• V1 compatibility surface: VLESS + WebSocket + TLS
• V3: direct Hysteria2 on Transit, terminated by Xray
• V2: chained Entry -> Transit VLESS + REALITY
• V4: chained Entry -> Transit Hysteria2
• persistent Telegram Proxy delivery through the bot
• public decoy site and hidden vault handoff on Transit
• host-local private handoff contracts for zapret2, Transit TCP/443 fronting and MTProto

• k3s / Helm runtime
• WireGuard
• separate standalone hysteria daemon path
• temporary “burner” MTProto access
• client-side OpenWRT / desktop-local obfuscation bundles

• Xray is the runtime center for public connection surfaces.
• Transit is the primary public endpoint; Entry is optional chain ingress.
• Public topology should stay static; ordinary user churn should update Xray over gRPC API instead of restarting the runtime.
• All public-facing profiles stay on 443.
• On constrained ~1 GB RAM hosts, keep the default rollout narrow: static public topology first, optional extra wrappers only when they are operationally justified.
• Public repo files describe contracts and templates; secrets and private camouflage live under host-local /etc/tracegate/private.

• tracegate-api: FastAPI service for users, devices, connections, revisions, admin flows, MTProto grants and scoped API tokens
• tracegate-dispatcher: outbox delivery worker with retry, backoff, dead-letter handling and optional ops alerts
• tracegate-bot: Telegram UX for provisioning, admin flows, Grafana access and feedback
• PostgreSQL: durable storage for users, revisions, dispatcher state and grants

Transit is the main public node. It can host:

• direct VLESS + REALITY
• optional VLESS + WS + TLS
• direct Hysteria2 through Xray
• the decoy site and hidden auth/vault handoff
• persistent Telegram Proxy
• host-local private TCP/443 fronting and zapret2 wrappers

Entry is optional and exists for chained V2/V4 rollout. It exposes the public chain ingress and forwards traffic toward Transit while sharing the same control-plane and bundle contract.

The public repository never stores the real packet manipulation or MTProto secrets. Instead it emits machine-readable handoff surfaces that private host-local wrappers can consume:

• runtime-contract.json under each agent runtime tree
• private runtime-state handoffs under the effective private runtime root
• seeded example files under deploy/systemd/private-example

This is the intended boundary for:

• private zapret2 logic
• private Transit TCP/443 fronting
• private MTProto runner configuration
• local post-render hooks and secret overlays

Tracegate 2 is designed so ordinary config issuance does not restart Xray.

The intended steady state is:

1. pre-seed a stable public topology
2. keep REALITY inbound mapping fixed, ideally through REALITY_MULTI_INBOUND_GROUPS
3. update users through Xray gRPC HandlerService
4. reload only when the structure changes

Typical structural changes that still require reload:

• new inbound layout
• changed REALITY group mapping
• changed routing rules
• changed public fronting layout

Ordinary user issuance, rotation and revocation should stay within the live API sync path.

The project can expose:

• Prometheus metrics from API, dispatcher, bot and agent surfaces
• Grafana with bot-delivered one-time access links
• pseudonymized user labels for safer dashboards
• dispatcher health and outbox alerts
• runtime and handoff validation through preflight tooling

• src/tracegate: application code
• bundles/base-entry, bundles/base-transit: public runtime bundle templates
• bundles/bot: bot guide and public bot-facing assets
• deploy/systemd: host deployment kit for plain Linux installs
• deploy/systemd/private-example: seeded examples for private overlays and wrappers
• alembic: database migrations
• tests: regression tests for API, bot, deployment and runtime logic

Use Docker Compose for the control-plane development stack:

cp .env.example .env
docker compose up --build
docker compose exec api tracegate-init-db
curl http://localhost:8080/health
pytest -q

Local development is mainly for the control plane and template logic. Host runtime deployment is covered by the systemd kit.

Tracegate 2 targets plain Linux hosts with systemd.

Start with the deployment kit in deploy/systemd:

• tracegate.env.example: shared control-plane and bundle-rendering values
• entry.env.example: Entry-only runtime values
• transit.env.example: Transit-only runtime values
• transit-single.env.example: single-file Transit replacement profile
• install.sh: installs the repo, Python package, units and seeded private examples
• install-runtime.sh: installs upstream runtime binaries
• render-materialized-bundles.sh: renders host-ready bundle files
• render-xray-centric-overlays.sh: optional full private xray.json overlay generator
• validate-runtime-contracts.sh: rollout preflight
• replace-transit-node.sh: Transit-only replacement workflow

Typical host flow:

sudo ./deploy/systemd/install.sh
sudo /opt/tracegate/deploy/systemd/install-runtime.sh
sudo /opt/tracegate/deploy/systemd/render-materialized-bundles.sh
sudo /opt/tracegate/deploy/systemd/validate-runtime-contracts.sh

Transit-only rebuild flow:

sudo TRACEGATE_INSTALL_ROLE=transit TRACEGATE_SINGLE_ENV_ONLY=true ./deploy/systemd/install.sh
sudo TRACEGATE_ENV_FILE=/etc/tracegate/tracegate.env /opt/tracegate/deploy/systemd/replace-transit-node.sh

The repository also ships a GitHub Actions workflow for Transit replacement:

• .github/workflows/transit-node-replacement.yml

For full deployment details, environment layout and private overlay rules, read deploy/systemd/README.md.

Important operator surfaces:

• POST /dispatch/reapply-base: resend current base bundle set to node agents
• POST /dispatch/reissue-current-revisions: reissue active user revisions
• tracegate-render-materialized-bundles: render public templates with operator values
• tracegate-render-xray-centric-overlays: generate host-local Xray replacements for the active runtime
• tracegate-validate-runtime-contracts: verify public/private handoff consistency before rollout

Useful operational rules:

• keep decoy auth credentials only in host env files
• keep MTProto secrets only in host-local files
• keep zapret2 policy logic out of the public repository
• prefer dedicated real domains for Telegram Proxy surfaces
• treat VLESS + WS + TLS as compatibility, not as the core architecture

The repository is designed so sensitive runtime logic can stay private:

• public bundle templates are safe to commit
• host-local overlays live under /etc/tracegate/private/overlays
• post-render hooks live under /etc/tracegate/private/render-hook.sh
• private obfuscation/fronting/MTProto helpers live under /etc/tracegate/private/{systemd,fronting,zapret,mtproto}
• agent-generated private runtime state lives under the effective private runtime root, typically /var/lib/tracegate/private

Do not commit:

• API tokens
• bot tokens
• MTProto secrets
• REALITY private keys
• private zapret2 rules or classifiers
• decoy auth credentials

The active Tracegate 2 runtime contract is xray-centric. Older names may still exist as compatibility aliases in code or migrations, but they resolve to the same public runtime path.

GPL-3.0-only. See LICENSE.