A modern, self-hosted Telegram Bot Builder with an intuitive web dashboard, one-click installation, Cloudflare D1 storage, and zero server maintenance.
Nyxx lets you build and manage Telegram bots through a beautiful web dashboard instead of editing code.
Deploy everything to your own Cloudflare account in minutes with the built-in installer. No servers, no VPS, no Docker, and no CLI required.
- What is Nyxx?
- Why Nyxx?
- Features
- Quick Start
- How It Works
- Dashboard Overview
- AI Assistant
- Architecture
- Repository Structure
- Installation
- Updating Nyxx
- Security
- Requirements
- Feature Matrix
- Screenshots
- FAQ
- Roadmap
- Changelog
- Contributing
- License
- Credits & Contact
Nyxx is a self-hosted Telegram bot builder that runs entirely on Cloudflare's free tier.
Instead of writing code, you use a visual dashboard to:
- Create and organize commands (text & photo responses)
- Build inline and reply keyboards without touching JSON
- Manage Telegram menu commands
- Add an AI assistant powered by OpenAI, Gemini, Groq, or any OpenAI-compatible API
- Manage users, bot profile info, and webhooks
All of your data — commands, users, settings, AI memory — lives in your own Cloudflare D1 database, inside your own Cloudflare account.
Unlike many Telegram bot panels that require a VPS or complicated setup, Nyxx is designed to be deployed entirely on Cloudflare:
- Zero server management — no VPS, no Docker, no SSH
- Global performance — served from Cloudflare's edge network
- Very generous free tier — Workers + D1 free plans cover most personal projects
- One-click installer — deploy, update, or delete your panel from a web wizard
- Easy updates — update from inside the dashboard itself
- Secure by design — webhook secrets, hashed passwords, and a hardened proxy
| Feature | Description |
|---|---|
| Unlimited commands | Text & photo responses |
| Nested commands | Organize commands into folders, navigate with breadcrumbs |
| Enable / Disable | Turn commands on and off without deleting them |
| Admin-only commands | Restrict commands to your admin users |
| Inline keyboards | URL, callback, and command buttons — built visually |
| Reply keyboards | Drag-and-drop button builder, no JSON required |
| Menu commands | Publish /help, /start, /settings… to Telegram with one click |
| Automatic webhooks | Registered, secured, and re-registered for you |
| Backup & Restore | Export and import all your bot data (commands, users, AI memory, settings) as a JSON file. |
| User Blocking | Block users entirely or only from the AI chatbot. |
| AI Multi‑Provider Fallback | Add up to 5 alternate AI providers as fallback if the main one fails. |
| AI Strict Mode | Force the AI to answer only using your instructions and knowledge bases. |
| AI RTL Support | Automatic right‑to‑left rendering for Persian (Farsi) and Arabic text. |
| AI Rate Limiting | Set per‑user request limits to prevent abuse. |
| Overview Dashboard | Real‑time statistics and quick actions on a new landing page. |
| Dashboard Performance | Improved caching and batch operations for faster loading. |
- Modern responsive interface, mobile friendly, dark UI
- Secure login with an initial setup wizard
- Live status indicators and toast notifications
- Manage everything from one place — no CLI needed
- See everyone who interacted with your bot
- Username + display name, with search support
- Assign admin roles right from the dashboard
- Change bot token (validated against Telegram, same-token re-save supported)
- Webhook URL with a one-click diagnostic test (reports what Telegram actually sees: URL match, pending updates, last delivery error)
- Change admin password
- Connection status + factory reset
Update your bot's profile without leaving Nyxx:
- Name, description, and short description
- Publish changes to Telegram instantly
Built into the dashboard — turn your bot into a chatbot:
- Multiple providers: OpenAI, Gemini, Groq, or a custom OpenAI-compatible endpoint
- Primary + fallback: if the main provider fails, the backup kicks in
- Custom system prompts
- Local knowledge bases (multiple, toggleable)
- Per-chat conversation memory
- AI Playground for testing prompts
- Suggested question buttons
- Rate limiting & safety controls
- Optional trigger conditions
- One-click provider connection testing
The fastest way to install, update, or manage Nyxx is the automated installer:
It's a guided wizard that walks you through:
- Account — paste a Cloudflare API token (it never leaves your browser)
- Proxy — pick the hosted proxy, or bring your own
- Scan — detects existing workers & D1 databases on your account
- Create — name your panel (or tap 🎲 for a random one) and deploy
The installer automatically:
- ✅ Creates a Cloudflare Worker
- ✅ Creates a D1 database
- ✅ Binds the database to the Worker
- ✅ Uploads and deploys the latest Worker code
- ✅ Gives you your dashboard URL
- ✅ Updates existing panels
- ✅ Deletes panels
- ✅ Manages D1 databases & bindings
It also shows the latest published version before you install, runs proxy health checks, and never hangs on a dead connection — every API call has a timeout with automatic retry.
No manual configuration required.
Nyxx is two pieces working together:
1. The installer (a static web page) talks to the Cloudflare API through a small CORS proxy, using your API token, to create the Worker, the D1 database, and their binding — all inside your Cloudflare account.
2. The worker (worker.js) is both your bot engine and your dashboard:
- Telegram sends updates to your worker's
/webhookendpoint - The webhook is protected by a secret token that only Telegram knows
- Commands, users, settings, and AI memory are stored in your D1 database
- The dashboard (served by the worker itself) is protected by a session login
Your bot data never touches a third-party server.
Manage your bot like a file explorer:
- Create, edit, and delete commands
- Organize commands into folders
- Navigate using breadcrumbs
- Enable / disable commands
- Restrict commands to admins only
Create beautiful Telegram inline keyboards without writing JSON:
| Button type | Description |
|---|---|
| Callback | Trigger an action |
| Command | Open another command |
| URL | Open websites or channels |
Design Reply Keyboards visually:
- Drag & organize buttons
- Link buttons to commands
- Toggle keyboard visibility per command
- No manual JSON editing
Publish Telegram's built-in menu commands (/help, /start, /settings, /about, …) directly from the dashboard — perfect for discovery.
View everyone who has interacted with your bot and search by username or display name.
Manage everything from a single page: bot token, webhook, password, connection status, and factory reset.
Update your bot's name, description, and short description — then publish to Telegram instantly.
Configure AI providers, system prompts, knowledge bases, memory, suggested questions, and safety limits — all from the dashboard.
Nyxx includes a full AI chatbot engine. Here's what you get:
- Providers: OpenAI, Gemini, Groq, or Custom (any OpenAI-compatible API)
- Main + fallback: configure a backup provider so the bot keeps working if the primary fails
- System prompt: control the bot's personality entirely
- Knowledge bases: add up to multiple content blocks that the AI uses to answer
- Memory: the bot remembers the conversation (with a clear-memory button and usage counter)
- Playground: test prompts and provider configs before going live
- Suggested questions: render quick-reply chips in chat
- Safety: rate limiting and optional trigger conditions (e.g. only respond to certain words)
┌─────────────────────────────┐
│ Installer (GitHub Pages) │
│ installer.html │
└──────────────┬──────────────┘
│ browser ⇄ CORS proxy (proxy.js)
▼
Cloudflare REST API
│
┌──────────────────────────┴──────────────────────────┐
▼ ▼
Cloudflare Worker (worker.js) Cloudflare D1
│ • Dashboard UI + session login • commands
│ • Telegram bot engine • users
│ • REST API for the dashboard • settings
│ • AI orchestration • AI memory
└──────────────┬──────────────────┬───────────────────┘
▼ ▼
Telegram (webhook, AI providers
secured by secret) (OpenAI / Gemini /
Groq / custom)
Nyxx/
│
├── installer.html The web wizard — token verification, proxy selection,
│ panel scanning, create/update/delete, custom worker names
│
├── worker.js The Nyxx panel — Telegram bot engine, dashboard UI,
│ REST API, authentication, D1 logic, AI assistant
│
├── proxy.js The CORS proxy that relays browser ⇄ Cloudflare API
│ requests (hardened: host allow-list + SSRF protection)
│
├── version.json Release metadata — powers the installer's version chip
│ and the panel's in-dashboard Update tab
│
├── logo.webp Project logo
│
└── README.md This file — the public GitHub README
Visit:
The installer handles everything automatically — creating the Worker, creating and binding the D1 database, uploading the latest code, and deploying.
If the installer can't reach the public proxy:
- Deploy
proxy.jsto your own Cloudflare Worker. - (Optional) Lock it down further with bindings:
ALLOWED_HOSTS— comma-separated host list overriding the default allow-listALLOW_ALL— set to"true"to opt back into unrestricted proxying (not recommended)
- Replace the proxy URL inside
installer.html. - Open the installer again and continue.
This fallback exists so you're never dependent on a single hosted proxy.
If you prefer to deploy without the installer:
- Create a Worker and a D1 database in the Cloudflare dashboard (or via
wrangler). - Create a
wrangler.toml:
name = "nyxx"
main = "worker.js"
compatibility_date = "2026-08-16"
[[d1_databases]]
binding = "DB" # must be named "DB" — worker.js reads env.DB
database_name = "nyxx"
database_id = "<your-d1-database-id>"
# Optional: a fixed admin password instead of the in-dashboard setup wizard
# [vars]
# ADMIN_PASS = "changeme"- Deploy:
npx wrangler deployThe database schema is created automatically on first run — no migration files needed. Then open your worker's URL and complete the setup wizard (or log in with ADMIN_PASS).
Updating is simple — and you can even do it from inside the panel.
The Update tab in your panel checks version.json, downloads the latest worker.js, deploys it to your Cloudflare account, and rotates the webhook secret automatically — so upgraded installs keep the same security guarantees.
- Download the latest release.
- Replace your Worker code.
- Deploy again.
Your D1 database and existing bot configuration remain intact.
Always create a database backup before major updates.
Nyxx is designed so deployment happens directly into your own Cloudflare account, and the panel is hardened against common attacks:
- API tokens stay in your browser. The installer never sends your Cloudflare token to any third-party server — it only goes to Cloudflare's own API.
- Everything belongs to you. Your Worker and your D1 database run under your Cloudflare account.
- Webhook secret token. Every webhook is registered with a
secret_token, and the panel rejects any delivery that doesn't carryX-Telegram-Bot-Api-Secret-Token. The secret is rotated automatically on token changes and in-panel updates. - Hashed admin passwords. Passwords are stored as
sha256$<hash>in D1 — never in plain text. Existing installs are re-hashed on the next password change. - Hardened CORS proxy. The default proxy only forwards to
api.cloudflare.com,raw.githubusercontent.com, and*.workers.dev, and blocks targets that resolve to private, loopback, link-local, or cloud-metadata addresses (SSRF protection). Errors are returned as CORS-safe JSON. - Protected sessions & headers. Session cookies are
HttpOnlywithSameSite=Lax, responses includenosniff,Referrer-Policy, andX-Frame-Options, and errors never leak stack traces.
The public proxy only forwards requests to the Cloudflare API. If you prefer, you can deploy your own copy using
proxy.js.
Before installing you'll need:
- A free Cloudflare account
- A Telegram bot created with @BotFather
- A modern web browser
Cloudflare's free plan is sufficient for most personal projects.
| Feature | Supported |
|---|---|
| Cloudflare Workers | ✅ |
| Cloudflare D1 | ✅ |
| Web Dashboard | ✅ |
| Mobile Friendly | ✅ |
| Secure Login | ✅ |
| Initial Setup Wizard | ✅ |
| Nested Commands / Folders | ✅ |
| Inline Keyboards | ✅ |
| Reply Keyboards | ✅ |
| Telegram Menu Commands | ✅ |
| User Management | ✅ |
| Admin-only Commands | ✅ |
| Text Responses | ✅ |
| Photo Responses | ✅ |
| Bot Information Editor | ✅ |
| Automatic Webhook | ✅ |
| Webhook Secret Token | ✅ |
| Webhook Diagnostic Test | ✅ |
| Hashed Passwords | ✅ |
| AI Assistant (multi-provider) | ✅ |
| AI Knowledge Bases | ✅ |
| AI Conversation Memory | ✅ |
| AI Playground | ✅ |
| In-dashboard Update | ✅ |
| Factory Reset | ✅ |
| One-click Installer | ✅ |
| Self Hosted | ✅ |
Yes. Nyxx is open-source and designed to work with Cloudflare's generous free plan.
No. Everything runs on Cloudflare Workers.
Yes. Every component belongs to you and can be self-hosted — including the installer's proxy.
Simply deploy your own copy of proxy.js and update the proxy URL inside installer.html. The repository includes the proxy source for exactly this reason.
No. The installer is designed so your API token stays inside your browser during installation and is only ever sent to Cloudflare's API.
OpenAI, Gemini, Groq, or any custom OpenAI-compatible API — with a primary provider and an automatic fallback.
No. Your bot data stays in your own D1 database. The only outbound calls are to Telegram, to the AI provider you explicitly configure, and to Cloudflare's API during updates.
Absolutely. worker.js is fully open source and intended to be modified.
Future ideas include:
- File uploads
- Video & audio responses
- Rich media support
- Multi-language dashboard
- Scheduled broadcasts
- Analytics dashboard
- Import / Export commands
- Backup & Restore
- Plugin system
- Theme customization
- New Overview Dashboard with statistics and quick actions.
- Backup & Restore – export/import all data.
- User Management Enhancements – block users, send private messages.
- AI Assistant Overhaul:
- Up to 5 alternate providers as fallback.
- Strict Mode (knowledge‑only answers).
- RTL support for Persian/Arabic.
- Rate limiting and memory trimming.
- Command Management – drag‑and‑drop reordering of keyboard buttons, move commands up/down.
- UI/UX Redesign – modern dark theme, Vazirmatn font, better mobile responsiveness.
- Performance – caching and batch DB operations.
- Security – webhook secret rotation on update.
- Bug fixes: command rename references, webhook test, same‑token updates, memory clear.
- Test Webhook works again. The button now uses a protected diagnostic endpoint that queries Telegram's
getWebhookInfoand reports the real state (URL match, pending updates, last delivery error) — no more401. - Re-saving the same bot token no longer fails. Tokens are only re-validated when they actually change; Telegram API calls retry transient failures (e.g.
429rate limits) and surface Telegram's own error message. - Safer setup & update ordering. Webhooks are registered with Telegram before secrets are persisted, so a failed registration can never lock out real deliveries.
- Admin passwords hashed (
sha256$) — backward compatible with existing installs - Telegram webhook secret tokens with automatic rotation
- CORS proxy is no longer an open relay (host allow-list + SSRF protection)
- Installer resilience: timeouts, retries, proxy health banner, live version info, custom worker names
Contributions are always welcome.
You can help by:
- Reporting bugs
- Suggesting features
- Improving documentation
- Opening Pull Requests
- Sharing ideas
Before submitting major changes, please open an issue to discuss your proposal.
This project is licensed under the MIT License.
Feel free to use, modify, and distribute it according to the license terms.
Created and maintained by Mahan (@Mahan07dev).
Special thanks to:
- Cloudflare
- Telegram
- Everyone who tests, reports bugs, and contributes to the project.
GitHub — https://github.com/Mahan07dev
Telegram — https://t.me/nyxx_official_channel
Made with ❤️ using Cloudflare Workers & Telegram Bot API.
If you like this project, don't forget to ⭐ the repository.