Open-source · Serverless · Stealth-aware
Modern VLESS / Trojan / VMess control plane on Cloudflare Workers + D1
_{Admin dashboard · User status portal · Smart subscription · Disguise skins · One-line install}

English · فارسی · Quick start · API token · Features · Security · Contributing

---

XRayMOD

XRayMOD is an open-source, serverless control plane for managing proxy users and subscription links on Cloudflare Workers with D1 storage.

You get a practical admin UI, a user-facing status page, smart subscription bundles, and optional disguise surfaces — without renting a VPS for the panel itself.

Operator responsibility: Comply with Cloudflare’s terms, local laws, and acceptable-use rules. This is infrastructure software — not permission to attack networks you do not control.

---

Why operators use it

Pain	What XRayMOD does
VPS cost & babysitting for a small panel	Runs on Cloudflare Workers + D1 (edge, pay-as-you-go)
Panel scanners & path guessing	Compulsory SECURE PATH (random UUID); bare /panel → silent 404
End users asking “how much traffic left?”	Public /{SECURE}/me/<uuid> portal with QR & copy
Weak subscription UX	Top-10 smart bundle: direct + clean IPs + CF ports + fingerprints
Hostile / filtered networks	Disguise skins + canary traps

---

Features

	Feature	Detail
🥷	Compulsory SECURE PATH	Panel / API / sub / portal only under a random UUID
🛡	Admin dashboard	Users · update check · CF-email login · custom domains · kill switch
📊	User status portal	Traffic, days left, QR — no admin login for end users
🎯	Smart subscription	Direct + clean IPs + CF ports · Clash / sing-box formats
🥷	Stealth skins	Silent 404 · CF 1101 · nginx · GitHub · WordPress · Access Denied
🕳	Canary traps	Fake paths log scanners without exposing the panel
💾	Backup & audit	Export/import · remote settings sync · admin action history
📡	ISP-aware clean IPs	Better picks for constrained carriers when data is available
🔐	Admin hardening	CF email login · 2FA · rate limiting · SECURE PATH
⚡	One-line install	Windows PowerShell/CMD · Linux · macOS · WSL
📱	Client-ready	v2rayNG ≥2.2.3 · sing-box ≥1.12 · Hiddify · Streisand · Clash

---

Tech stack

Layer	Technology
Runtime	Cloudflare Workers
Database	Cloudflare D1 (SQLite at the edge)
Language	TypeScript
Admin UI	Next.js (static export into Worker assets)
Installers	Bash · PowerShell
Tooling	Wrangler · npm

graph TD
    Internet --> Edge[Cloudflare Edge Worker]
    Edge --> Gate[SECURE PATH gate - silent 404]
    Edge --> Disguise[Disguise / static responses]
    Edge --> Admin[Admin API + Admin Dashboard]
    Edge --> Sub[Subscription endpoints]
    Edge --> Portal["/{SECURE}/me user portal"]
    Edge --> D1[(D1 Database - users, settings, audit)]

Loading

---

Requirements

Your machine

• Windows 10+, macOS 12+, or modern Linux
• Internet access to api.cloudflare.com and GitHub
• Ability to run PowerShell or Bash

Cloudflare

• A Cloudflare account (Free plan is enough for many personal setups)
• Permission to create Workers and D1 databases
• An API token with Workers edit rights (see next section)

Optional (manual / contributor workflow)

• Node.js 20+
• npm 10+
• Wrangler 3+

---

Create a Cloudflare API token

The installer never uploads your token to this GitHub repo. It stays on your machine and is used only against Cloudflare APIs. Prefer a scoped token, not Global API Key.

Step-by-step

1. Sign in to the Cloudflare Dashboard.
2. Open My Profile (top-right avatar) → API Tokens.
   Direct link: https://dash.cloudflare.com/profile/api-tokens
3. Click Create Token.
4. Under API token templates, choose Edit Cloudflare Workers → Use template.
   This is the recommended starter for XRayMOD.
5. Review (and tighten if you want):
   • Account resources → include only the account you will deploy to
   • Zone resources → only if you will attach custom domains (otherwise you can leave as the template suggests)
6. Click Continue to summary → Create Token.
7. Copy the token once and store it in a password manager. Cloudflare will not show it again.
8. Paste it into the XRayMOD installer when prompted.

What the token is used for

Action	Why
Create / update Worker	Host the panel + proxy edge
Create / bind D1	Persist users & settings
Optional custom domain	Route your domain to the Worker

Safety checklist

• Do not paste the token into Issues, PRs, Discord, or Telegram groups
• Do not commit it to git or put it in screenshots
• Rotate the token if it ever leaks
• Prefer revoking old tokens after you finish a one-off machine install

If Cloudflare shows account/payment errors, fix billing / account status first — wrangler whoami (or the installer) will fail until the account is healthy.

---

Quick start (≈5 minutes)

1) Run the installer

Windows PowerShell (prompt starts with PS):

irm https://raw.githubusercontent.com/askarniroomand/XRayMOD/main/install.ps1 | iex

Windows CMD:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (iwr -UseBasicParsing 'https://raw.githubusercontent.com/askarniroomand/XRayMOD/main/install.ps1').Content"

Linux / macOS / WSL:

bash <(curl -fsSL https://raw.githubusercontent.com/askarniroomand/XRayMOD/main/install.sh)

2) Answer three prompts

Step	You enter	Notes
1	Cloudflare API token	From the section above
2	Admin username	Prefer binding CF email later in the panel
3	Admin password	Use a long, unique password

Everything else (Node tooling, clone, D1, UI build, Worker deploy, bootstrap) is automated. Git is not required on your machine for the one-line path.

3) Save the URLs the installer prints

URL pattern	Purpose
/{SECURE_PATH}/login	Admin login — keep private
/{SECURE_PATH}/panel	Admin dashboard
/{SECURE_PATH}/sub/<USER_UUID>	Subscription (Base64 by default)
/{SECURE_PATH}/me/<USER_UUID>	User traffic / days / QR
…/sub/<USER_UUID>?format=clash	Clash / Mihomo YAML
…/sub/<USER_UUID>?format=singbox	sing-box JSON

Gen 1.9.12+: Bare /panel, /api/*, /sub/* without the SECURE PATH return 404. Always share links that include the UUID path. See CHANGELOG-1.9.12.md.

---

After install — first 10 minutes

1. Open /{SECURE_PATH}/login and sign in with the credentials you set.
2. Create a test user (traffic + expiry).
3. Copy the subscription link into Hiddify / v2rayNG / Clash / sing-box.
4. Open /{SECURE_PATH}/me/<uuid> in a browser to verify the status portal.
5. In Admin settings, pick a disguise skin and (recommended) bind Cloudflare email as login.
6. Store SECURE_PATH, Worker hostname, and admin password in your password manager.

---

Manual install (developers)

Clone → D1 → build → deploy

git clone https://github.com/askarniroomand/XRayMOD.git
cd XRayMOD
npm install
npm install --prefix frontend
npm run build:ui
npx wrangler login
npx wrangler d1 create xraymod-db
# paste database_id into wrangler.toml
npx wrangler deploy

Bootstrap admin (first time):

curl -X POST "https://YOUR_WORKER.workers.dev/install" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourStrongPass123"}'

Then open:

https://YOUR_WORKER.workers.dev/<SECURE_PATH>/login
https://YOUR_WORKER.workers.dev/<SECURE_PATH>/panel

More detail: DEPLOY.md.

---

Architecture

High-level

graph TD
    Clients[Clients v2rayNG, etc.] --> Edge[Cloudflare Network Worker]
    Admin[Admin browser] --> Edge
    Edge --> Router[Worker router.ts]
    Router --> Processors[processors/]
    Router --> Proxy[proxy/]
    Router --> API[api/]
    Router --> Portal[user-portal]
    Portal --> D1[(D1 SQLite)]
    API --> D1

Loading

Canonical source of truth

Path	Role
worker/	Production runtime — routing, auth, sub, portal
frontend/	Admin panel UI
installer/ + install.*	Bootstrap onto a Cloudflare account
telegram-bot/	Optional multi-panel Telegram operator bot
docs/	Human documentation and assets
backend/	Legacy / optional Python experiments — not required for Workers deploy

Request flow (simplified)

1. Request hits Worker fetch (worker/index.ts)
2. Router classifies: install · static · API · subscription · proxy · portal
3. Auth middleware gates admin APIs
4. D1 reads/writes users and settings
5. Response is panel JSON/HTML, subscription payload, or a disguise page

---

Project structure

graph TD
    Root[XRayMOD/] --> Worker[worker/]
    Root --> Frontend[frontend/]
    Root --> Installer[installer/]
    Root --> Bot[telegram-bot/]
    Root --> Docs[docs/]
    Root --> Scripts[scripts/]
    Root --> InstallSh[install.sh]
    Root --> InstallPs1[install.ps1]
    Root --> Wrangler[wrangler.toml]

    Worker --> Api[api/]
    Worker --> Processors[processors/]
    Worker --> Proxy[proxy/]
    Worker --> Lib[lib/]
    Worker --> Index[index.ts]
    Worker --> Router[router.ts]

Loading

---

Configuration

Variable / setting	Where	Notes
API token	Installer prompt only	Never commit
D1 database_id	Local wrangler config after install	Template uses placeholders in git
Access UUID / SECURE PATH	Generated at deploy	Treat as a secret path
Admin credentials	Bootstrap install	Rotate if leaked
Disguise mode	Panel settings	Skin for unknown routes
Protocol options	Panel / API	VLESS · Trojan · VMess related settings

See .env.example and SECURITY.md.

---

API overview

Admin APIs are path-scoped behind the panel access UUID.

Area	Methods	Notes
Auth login/logout	POST	Rate-limited
Users CRUD	GET/POST/PATCH/DELETE	Admin session required
Settings	GET/PUT	Admin session required
Nodes / backends	GET/POST	Admin session required
Subscription	GET	User UUID; format query param
Health	GET	Liveness

Full OpenAPI export is on the roadmap. Until then, inspect worker/api/* and panel network calls.

---

Roadmap

• Workers + D1 panel core
• /me status portal
• Smart subscription bundle
• One-line cross-platform install
• Public OpenAPI document
• Miniflare unit/integration tests in CI
• Signed release artifacts
• Multi-language panel UI packs
• Hardened error responses (no internal leakage)

See ROADMAP.md and CHANGELOG.md.

---

Known issues

Issue	Severity	Workaround
GitHub raw CDN can cache install scripts briefly	Medium	Re-run after a minute
Dual historical trees (backend/ vs Worker) may confuse new contributors	Medium	Treat worker/ as canonical
Limited automated tests in early public tags	Medium	Use smoke / e2e scripts; contribute tests
Some 500 paths may be too verbose	Low–Med	Prefer generic client errors

Issues: https://github.com/askarniroomand/XRayMOD/issues

---

FAQ

Is a VPS required?

No for the control plane. The panel runs on Cloudflare Workers + D1. Proxy backends/nodes are a separate concern depending on how you route user traffic.

Does the free Cloudflare plan work?

Yes for many personal setups. Watch Workers request limits and D1 quotas as you scale.

Where is my API token stored?

Only on your machine during install, sent only to Cloudflare APIs. Never commit it. See SECURITY.md.

Why do I get 404 on /panel?

Gen 1.9.12 requires the SECURE PATH UUID prefix. Use the full URL printed by the installer.

Can I use Hiddify / v2rayNG?

Yes. Import the subscription URL. Clash and sing-box formats are available via query parameters.

How do I report a security issue?

Privately via Telegram @MRROBOT_DT — do not open a public issue with secrets.

Is this legal?

Laws vary. You are solely responsible for lawful use and compliance with Cloudflare’s terms.

---

Contributing

Read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

git clone https://github.com/askarniroomand/XRayMOD.git
cd XRayMOD
npm install
# open a feature branch, make changes, PR against main

Small docs PRs and tests are excellent first contributions.

---

Changelog & versioning

• CHANGELOG.md
• Semantic versioning: MAJOR.MINOR.PATCH
• GitHub Releases via tag vX.Y.Z

---

License

MIT © Askar Niroomand & Pakrohk — see LICENSE.

---

Authors

	GitHub
Askar Niroomand	@askarniroomand
Pakrohk	@Pakrohk

---

Contact

Channel	Link
Authors	@askarniroomand · @Pakrohk
Telegram	t.me/MRROBOT_DT
Security	SECURITY.md
Persian docs	README.fa.md

---

_{XRayMOD · Cloudflare Workers + D1}