README.md

---
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_WORKERS_TOKEN
    description: Cloudflare API token for automatic Worker proxy and KeepAlive setup.
---

<!-- Badges -->
[![GitHub Stars](https://img.shields.io/github/stars/somratpro/hugging8n?style=flat-square)](https://github.com/somratpro/hugging8n)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![HF Space](https://img.shields.io/badge/🤗%20HuggingFace-Space-blue?style=flat-square)](https://huggingface.co/spaces)
[![n8n](https://img.shields.io/badge/n8n-Workflow-orange?style=flat-square)](https://n8n.io)

**Self-hosted n8n workflow automation — free, no server needed.** Hugging8n runs [n8n](https://n8n.io) 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](#-features)
- [🎥 Video Tutorial](#-video-tutorial)
- [🚀 Quick Start](#-quick-start)
- [🌐 Cloudflare Proxy Setup](#-cloudflare-proxy-setup)
- [💾 Persistent Backup](#-persistent-backup)
- [💓 Staying Alive](#-staying-alive)
- [🔐 Security & Advanced *(Optional)*](#-security--advanced-optional)
- [💻 Local Development](#-local-development)
- [🏗️ Architecture](#-architecture)
- [🐛 Troubleshooting](#-troubleshooting)
- [📚 Links](#-links)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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:** Uses `CLOUDFLARE_WORKERS_TOKEN` to automatically set up a cron-triggered keep-awake worker at boot.
- 🐳 **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](https://youtu.be/cfMruo5dlF8?si=elM6Mnmh0oQIyxp2).

## 🚀 Quick Start

### Step 1: Duplicate this Space

[![Duplicate this Space](https://huggingface.co/datasets/huggingface/badges/resolve/main/duplicate-this-space-xl.svg)](https://huggingface.co/spaces/somratpro/Hugging8n?duplicate=true)

### 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](https://dash.cloudflare.com/profile/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.

## 💾 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)*

Your Space will automatically be kept awake by a background Cloudflare Worker when you configure the `CLOUDFLARE_WORKERS_TOKEN` secret. The worker uses a cron trigger to regularly ping your Space's `/health` endpoint. The dashboard displays the current keep-alive worker status.

## 🔐 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` | — | Extra domains to proxy, merged with built-in defaults. Set to `*` to proxy all external traffic. Leave unset to use defaults only. |
| `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 |
| `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set to `false` to disable the automatic Cloudflare KeepAlive worker |

## 💻 Local Development

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

**With Docker:**

```bash
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. Use `CLOUDFLARE_PROXY_DOMAINS=*` to proxy all external traffic.
- **Workflows not saving:** Check if `HF_TOKEN` has **Write** access to your account.
- **Space keeps sleeping:** Add `CLOUDFLARE_WORKERS_TOKEN` as a Space secret to enable automatic keep-awake monitoring via Cloudflare Workers.
- **Authentication errors:** n8n v2 uses its own internal users; ensure you created the owner account on first run.

## 🌟 More Projects

Similar projects by [@somratpro](https://github.com/somratpro) — all free, one-click deploy on HF Spaces:

| Project | What it runs | HF Space | GitHub |
| :--- | :--- | :--- | :--- |
| **HuggingFlow** | DeerFlow — deep research agent | [Space](https://huggingface.co/spaces/somratpro/HuggingFlow) | [Repo](https://github.com/somratpro/HuggingFlow) |
| **HuggingMes** | Hermes — Self-hosted agent gateway | [Space](https://huggingface.co/spaces/somratpro/HuggingMes) | [Repo](https://github.com/somratpro/huggingmes) |
| **HuggingClaw** | OpenClaw — Claude Code in the browser | [Space](https://huggingface.co/spaces/somratpro/HuggingClaw) | [Repo](https://github.com/somratpro/huggingclaw) |
| **HuggingClip** | Paperclip — AI agent orchestration platform | [Space](https://huggingface.co/spaces/somratpro/HuggingClip) | [Repo](https://github.com/somratpro/huggingclip) |
| **HuggingPost** | Postiz — social media scheduler | [Space](https://huggingface.co/spaces/somratpro/HuggingPost) | [Repo](https://github.com/somratpro/HuggingPost) |

## 📚 Links

- [n8n Documentation](https://docs.n8n.io)
- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
- [Cloudflare Workers](https://workers.cloudflare.com/)

## ❤️ 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](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT — see [LICENSE](LICENSE) for details.

---
*Made with ❤️ by [@somratpro](https://github.com/somratpro)*