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_PROXY_URL
    description: Your Cloudflare Worker URL to bypass platform blocks (Telegram/Discord).
---

<!-- 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)
- [🚀 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 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

[![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 (to enable automatic backup).
- `CLOUDFLARE_PROXY_URL` – *(Optional but Recommended)* Your Cloudflare Worker URL to bypass platform blocks. check [Setup Guide](#-cloudflare-proxy-setup).
- `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](https://dash.cloudflare.com/?to=/:account/workers-and-pages).
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](./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

```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/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](https://docs.n8n.io)
- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
- [Cloudflare Workers](https://workers.cloudflare.com/)

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