README.md

metadata

title: Hugging8n
emoji: 🔗
colorFrom: red
colorTo: yellow
sdk: docker
app_port: 7861
pinned: true
license: mit
secrets:
  - name: HF_TOKEN
    description: HuggingFace token with write access. Used for automatic workspace backup.
  - name: CLOUDFLARE_PROXY_URL
    description: Your Cloudflare Worker URL to bypass platform blocks (Telegram/Discord).

Self-hosted n8n workflow automation — free, no server needed. Hugging8n runs n8n on HuggingFace Spaces, providing a 24/7 automation engine for your workflows. It includes a premium management dashboard, automatic persistent backup to HF Datasets, and built-in connectivity fixes to bypass platform restrictions. Deploy in minutes on the free HF Spaces tier with full data persistence.

Table of Contents

• ✨ Features
• 🚀 Quick Start
• 🌐 Cloudflare Proxy Setup
• 💾 Persistent Backup
• 💓 Staying Alive
• 🔐 Security & Advanced (Optional)
• 💻 Local Development
• 🏗️ Architecture
• 🐛 Troubleshooting
• 📚 Links
• 🤝 Contributing
• 📄 License

✨ Features

• ⚡ Zero Config: Duplicate this Space, set HF_TOKEN, and start automating – no other setup needed.
• 💾 Persistent Backup: Workflows, credentials, and settings automatically sync to a private HF Dataset, preserving your data across restarts.
• 🔐 Secure by Default: Uses n8n's native user management and restricted file permissions (umask 0077).
• 🌐 Built-in Connectivity: Includes Transparent Outbound Proxying and DNS-over-HTTPS (DoH) to bypass Hugging Face networking blocks for Telegram, Discord, and others.
• 📊 Premium Dashboard: Beautiful Web UI at / for real-time monitoring of uptime, sync health, and n8n status.
• ⏰ Easy Keep-Alive: Set up a one-time UptimeRobot monitor directly from the dashboard to keep your free Space awake.
• 🐳 Optimized Infrastructure: Minimal resource usage with clean startup logs and production-ready proxying.

🚀 Quick Start

Step 1: Duplicate this Space

Step 2: Add Your Secrets

Navigate to your new Space's Settings, scroll down to Variables and secrets, and add:

• HF_TOKEN – Your HuggingFace token with Write access (to enable automatic backup).
• CLOUDFLARE_PROXY_URL – (Optional but Recommended) Your Cloudflare Worker URL to bypass platform blocks. check Setup Guide.
• CLOUDFLARE_PROXY_SECRET – (Optional, Security Recommended) Shared secret used between Space and Worker to prevent proxy abuse.

Step 3: Deploy & Initialize

The Space will build and start automatically. Once ready:

1. Visit the Space URL.
2. Click Open n8n Editor.
3. Create your Owner account (this is your primary login).

Step 4: Monitor & Manage

Use the built-in dashboard at the root URL (/) to track:

• Uptime: Real-time uptime monitoring.
• Sync Status: Visual indicators for your workflow backups.
• Keep-Alive: Setup tool for external monitors.

🌐 Cloudflare Proxy Setup

Hugging Face Free Tier blocks outgoing connections to some services (Telegram, Discord, etc.). Hugging8n includes a transparent proxy system to bypass this.

1. Go to Cloudflare Workers.
2. Create a new Worker using "Start with Hello World!" template
3. choose worker name (e.g. h8n-proxy) and deploy.
4. Click on "Edit Code" button, paste the code from cloudflare-worker.js.
5. Click on "Deploy" button.
6. Copy the Worker URL (e.g., https://h8n-proxy.yourname.workers.dev).
7. Add this URL as the CLOUDFLARE_PROXY_URL secret in your Hugging8n Space settings.
8. (Optional, Recommended) In Cloudflare Worker settings, add a secret binding named CLOUDFLARE_PROXY_SECRET.
9. (Optional, Recommended) Add the same value in your Space secrets as CLOUDFLARE_PROXY_SECRET.

If you skip steps 8-9, proxying still works. The secret simply adds request authentication between your app and worker.

Optional Worker vars for tighter control:

• ALLOWED_TARGETS (comma-separated, defaults to Telegram/Discord hosts)
• ALLOW_PROXY_ALL (false by default; set true only if you fully trust your setup)

💾 Persistent Backup

Hugging8n automatically creates a private dataset named hugging8n-backup in your Hugging Face account.

• Restore: On startup, it pulls the latest state from your dataset.
• Sync: Periodically (every 3 minutes by default), it pushes updates to the dataset.
• Status: View current sync health on the Hugging8n Dashboard.

Variable	Default	Description
SYNC_INTERVAL	180	Backup frequency in seconds

💓 Staying Alive (Recommended on Free HF Spaces)

To help keep your Space awake, set up an external UptimeRobot monitor directly from the dashboard UI.

1. Open your Space's dashboard (/).
2. Find the Keep Space Awake section.
3. Paste your UptimeRobot Main API key.
4. Click Create Monitor.

Hugging8n will automatically create a monitor for your Space's /health endpoint.

🔐 Security & Advanced (Optional)

Customize your instance with these environment variables:

Variable	Default	Description
GENERIC_TIMEZONE	UTC	Timezone for your n8n instance
N8N_LOG_LEVEL	error	Set to info or debug for more details
CLOUDFLARE_PROXY_DOMAINS	(default list)	Comma-separated domains to proxy (or * for all)
CLOUDFLARE_PROXY_SECRET	—	Optional shared secret for app-to-worker proxy authentication
SPACE_HOST_OVERRIDE	—	Override detected host for custom domains
N8N_STARTUP_TIMEOUT	180	Max seconds to wait for n8n readiness before fail-fast
UPTIMEROBOT_SETUP_ENABLED	true	Enable/disable dashboard helper endpoint
UPTIMEROBOT_RATE_LIMIT_PER_MINUTE	5	Per-IP rate limit for helper endpoint

💻 Local Development

git clone https://github.com/somratpro/hugging8n.git
cd hugging8n
cp .env.example .env
# Edit .env with your secrets

With Docker:

docker build -t hugging8n .
docker run -p 7861:7861 --env-file .env hugging8n

🏗️ Architecture

• Dashboard (/): Management, monitoring, and keep-alive tools.
• n8n Editor (/home/workflows): All other paths are proxied to the internal n8n instance.
• Health Check (/health): Used for uptime monitoring and readiness probes.
• Sync Engine: Background process managing HF Dataset persistence.
• Transparent Proxy: Intercepts requests to blocked domains and routes them via Cloudflare.

🐛 Troubleshooting

• Telegram/Discord not connecting: Ensure CLOUDFLARE_PROXY_URL is set correctly.
• Workflows not saving: Check if HF_TOKEN has Write access to your account.
• Space keeps sleeping: Use the dashboard to set up an UptimeRobot monitor.
• Authentication errors: n8n v2 uses its own internal users; ensure you created the owner account on first run.

📚 Links

• n8n Documentation
• Hugging Face Spaces
• Cloudflare Workers

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT — see LICENSE for details.

---

Made with ❤️ by @somratpro