teremir/ratsomclip

<!-- Badges -->    

Run your own AI agent orchestration platform — free, no server needed. HuggingClip deploys Paperclip on Hugging Face Spaces, giving you a persistent AI agent platform with NVIDIA models via OpenCode and optional Gemini support. Deploy in minutes on the free HF Spaces tier (2 vCPU, 16GB RAM) with automatic database backup to a private HF Dataset so your agents, tasks, and conversations survive restarts.

Table of Contents

• —✨ Features
• —🚀 Quick Start
• —🔑 Configuration
• —🤖 LLM Providers
• —🌐 Cloudflare Proxy *(Optional)*
• —💾 Database Backup *(Optional)*
• —💓 Staying Alive
• —💻 Local Development
• —🏗️ Architecture
• —🐛 Troubleshooting
• —📚 Links
• —🤝 Contributing
• —📄 License

✨ Features

• —🤖 NVIDIA via OpenCode: Run OpenCode-backed agents with one or more NVIDIA API keys, plus optional Gemini support.
• —⚡ One-click deploy: Duplicate the Space and add your API key — nothing else needed to get started.
• —💾 Persistent Database: PostgreSQL database auto-backed up to a private HF Dataset and restored on every restart — no data loss.
• —📊 Visual Dashboard: Real-time status dashboard at / with Paperclip service health, backup status, and uptime.
• —⏰ Keep-Alive: Uses CLOUDFLARE_WORKERS_TOKEN to automatically set up a cron-triggered keep-awake worker at boot.
• —🌐 Cloudflare Proxy: Auto-provisions a Cloudflare Worker proxy for blocked outbound connections.
• —🔒 Secure by Default: Auth secrets randomly generated on first boot and persisted across restarts.
• —🏠 100% HF-Native: Runs entirely on Hugging Face's free infrastructure.

🚀 Quick Start

Step 1: Duplicate this Space


Step 2: Add Your Secrets

In your new Space's Settings → Variables and secrets, add at least one LLM key under Secrets:

[!TIP] Add HF_TOKEN (a token with write access to your account) to enable database backup persistence. Without it, data is lost on restart.

Step 3: Deploy & Run

The Space builds automatically. Monitor progress in the Logs tab. First build takes ~60s; subsequent builds are cached.

Step 4: Set Up Admin Account

On first boot, the dashboard at / shows an admin setup link. Click it to create your admin account and complete Paperclip onboarding.

🔑 Configuration

Required

No secrets are strictly required to start, but you need at least one LLM key to use agents:

Recommended

Advanced

🤖 LLM Providers

Set the relevant provider secret and Paperclip will use it automatically when you configure agents:

NVAPI_KEYS accepts one or more comma-separated NVIDIA API keys. HuggingClip writes them into the OpenCode runtime config and rotates them across invocations.

🌐 Cloudflare Proxy (Optional)

Hugging Face Spaces sometimes blocks outbound connections to external APIs. HuggingClip includes the same transparent Cloudflare proxy approach used in HuggingClaw and Hugging8n.

Automatic setup:

1. 1.Create a Cloudflare API Token (Workers Scripts: Edit permission).
2. 2.Add CLOUDFLARE_WORKERS_TOKEN as a Space secret.
3. 3.Restart the Space.

HuggingClip will:

• —Create or update a Worker named from your Space host
• —Generate a private shared secret automatically
• —Transparently route outbound traffic through Cloudflare

💾 Database Backup (Optional)

HuggingClip automatically backs up your Paperclip PostgreSQL database to a private HF Dataset on every sync cycle and restores it on startup.

What's backed up:

• —Full PostgreSQL SQL dump
• —Paperclip config, secrets, and data files
• —Packaged as snapshots/latest.tar.gz in your huggingclip-backup dataset

Setup: Add HF_TOKEN (write-access token) to Space secrets. The dataset <your-username>/huggingclip-backup is created automatically on first sync.

[!NOTE] Without HF_TOKEN, the app runs fine but all data is lost on Space restart. Set it up from the start to avoid losing agent configurations.

💓 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.

💻 Local Development

git clone https://github.com/somratpro/huggingclip.git
cd huggingclip
cp .env.example .env
# Edit .env with your NVAPI_KEYS, optional GEMINI_API_KEY, and HF_TOKEN

With Docker:

docker build -t huggingclip .
docker run -p 7861:7861 \
  -e HF_TOKEN=hf_xxxx \
  -e NVAPI_KEYS=nvapi-xxxx,nvapi-yyyy \
  -v paperclip_data:/paperclip \
  huggingclip

With Docker Compose:

docker-compose up -d
# Dashboard: http://localhost:7861/
# Paperclip UI: http://localhost:7861/app/

🏗️ Architecture

HuggingClip/
├── Dockerfile           # Multi-stage build: compile Paperclip from source
├── start.sh             # Orchestrator: PostgreSQL, restore, config, launch
├── health-server.js     # Dashboard, /health endpoint, reverse proxy to Paperclip
├── paperclip-sync.py    # PostgreSQL backup/restore to HF Dataset
├── cloudflare-proxy.js  # Transparent outbound proxy for blocked domains
├── .env.example         # Environment variable reference
└── README.md

Startup sequence:

1. 1.Validate LLM provider keys (warn if none configured).
2. 2.Start PostgreSQL and create database.
3. 3.Generate or restore auth secrets (persist across restarts).
4. 4.Restore database and data files from HF Dataset backup (if HF_TOKEN set).
5. 5.Start background sync loop (every SYNC_INTERVAL seconds).
6. 6.Launch health server on port 7861 (dashboard + reverse proxy).
7. 7.Generate Paperclip instance config on first boot.
8. 8.Launch Paperclip server on port 3100.
9. 9.Bootstrap first admin account (shows invite URL in dashboard).
10. 10.On SIGTERM, wait for any in-flight sync, run final backup, exit cleanly.

Port layout:

🐛 Troubleshooting

No LLM providers configured warning Set at least one of NVAPI_KEYS, GEMINI_API_KEY, or NVIDIA_BASE_URL in Space secrets/variables.

Admin setup link not showing Check Space logs — if Paperclip started but admin setup link is missing, the bootstrap ran but found an existing account. Log in at /app/.

Backup not uploading Verify HF_TOKEN is set and has write access. Check the dashboard backup status. Run manually: python3 /app/paperclip-sync.py sync from inside the container.

Data lost after restart HF_TOKEN is not set. Add it and the next restart will restore from backup. The backup also needs to have been run at least once before the restart.

Space keeps sleeping Add CLOUDFLARE_WORKERS_TOKEN as a Space secret to enable automatic keep-awake monitoring via Cloudflare Workers.

Paperclip unreachable (502 errors) Wait 60–90s after boot for Paperclip to initialize. If it stays unreachable, check logs for PostgreSQL connection errors or memory issues.

Backup too large (>50MB) Reduce SYNC_MAX_FILE_BYTES to skip large backups, or increase it. Alternatively, archive old agent runs inside Paperclip to reduce DB size.

Stack overflow in recovery chains Deep issue-dependency chains (1000+ nodes) created by runaway agents can hit a 500-node limit in the upstream recovery graph traversal. This is patched conservatively in the Dockerfile. File an issue upstream at paperclipai/paperclip if you need larger chains.

🌟 More Projects

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

📚 Links

• —Paperclip Docs
• —Paperclip GitHub
• —HuggingFace Spaces Docs

❤️ Support

If HuggingClip 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](https://github.com/somratpro) for the Paperclip community.