title	Hugging8n
emoji	🔗
colorFrom	red
colorTo	yellow
sdk	docker
app_port	7861
pinned	true
license	mit
secrets	name description HF_TOKEN HuggingFace token with write access. Used for automatic workspace backup. name description CLOUDFLARE_WORKERS_TOKEN Cloudflare API token for automatic Worker proxy setup.

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
• 🎥 Video Tutorial
• 🚀 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 via Cloudflare Workers for Telegram, WhatsApp-related APIs, Google APIs, Discord, and other external services.
• 📊 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.

🎥 Video Tutorial

Watch a quick walkthrough on YouTube: Deploying Hugging8n on HF Spaces.

🚀 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 (for automatic backup).
• CLOUDFLARE_WORKERS_TOKEN – (Highly Recommended) Cloudflare API token. Hugging8n will automatically create and configure a Worker proxy for you.

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 often restricts outbound connections to services like Telegram, Discord, and WhatsApp. Hugging8n solves this with a Transparent Outbound Proxy via Cloudflare Workers.

⚡ Automatic Setup (Recommended)

This is the easiest way. Hugging8n will handle the deployment for you.

1. Create a Cloudflare API Token:
   • Go to API Tokens.
   • Create Token -> Edit Cloudflare Workers template.
   • Ensure it has Account: Workers Scripts: Edit permissions.
2. Add the token as a secret named CLOUDFLARE_WORKERS_TOKEN in your Space Settings.

What happens next?

• Hugging8n automatically creates a Worker named after your Space.
• It generates a secure, private CLOUDFLARE_PROXY_SECRET.
• All restricted outbound traffic is automatically routed through this Worker.

🛠️ Manual Setup

If you prefer to manage the Worker yourself:

1. Create a new Cloudflare Worker.
2. Paste the code from cloudflare-worker.js and deploy.
3. Add the Worker URL to your Space as CLOUDFLARE_PROXY_URL.
4. (Optional) Set a CLOUDFLARE_PROXY_SECRET in both the Worker (as a variable) and the Space (as a secret).

💾 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_WORKERS_TOKEN	—	Cloudflare API token for automatic Worker setup
CLOUDFLARE_PROXY_DOMAINS	*	Comma-separated domains to proxy (or * for all external traffic)
CLOUDFLARE_PROXY_SECRET	—	Optional shared secret for proxy authentication
CLOUDFLARE_WORKER_NAME	auto	Custom name for the automatically created Worker
CLOUDFLARE_ACCOUNT_ID	auto	Optional Cloudflare account ID override
SPACE_HOST_OVERRIDE	—	Override detected host for custom domains
N8N_STARTUP_TIMEOUT	180	Max seconds to wait for n8n readiness
UPTIMEROBOT_SETUP_ENABLED	true	Enable/disable dashboard helper endpoint
UPTIMEROBOT_RATE_LIMIT_PER_MINUTE	5	Rate limit for monitor creation

💻 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/Google/WhatsApp not connecting: Ensure CLOUDFLARE_WORKERS_TOKEN or CLOUDFLARE_PROXY_URL is set correctly, or keep CLOUDFLARE_PROXY_DOMAINS=*.
• 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.

🌟 More Projects

Similar projects by @somratpro — all free, one-click deploy on HF Spaces:

Project	What it runs	HF Space	GitHub
HuggingClaw	OpenClaw — Claude Code in the browser	Space	Repo
HuggingClip	Paperclip — AI agent orchestration platform	Space	Repo

📚 Links

• n8n Documentation
• Hugging Face Spaces
• Cloudflare Workers

❤️ Support

If Hugging8n saves you time, consider buying me a coffee to keep the projects alive!

USDT (TRC-20 / TRON network only)

TELx8TJz1W1h7n6SgpgGNNGZXpJCEUZrdB

Warning

Send USDT on TRC-20 network only. Sending other tokens or using a different network will result in permanent loss.

🤝 Contributing

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

📄 License

MIT — see LICENSE for details.

---

Made with ❤️ by @somratpro