spaceclip
technicalboy2023/spaceclip
π Self-host your own AI agent platform on Hugging Face Spaces for FREE. Run Claude Code, OpenAI GPT, and Google Gemini agents with persistent PostgreSQL storage, auto backup to HF Dataset, Cloudflare proxy, and keep-awake. Zero server needed.
InstalaΓ§Γ£o
npx convez-ai technicalboy2023/spaceclip1 comando no terminal: detecta o formato do repositΓ³rio (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
MΓ©tricas
README
A traduΓ§Γ£o para o portuguΓͺs deste README ainda estΓ‘ na fila.
title: HuggingClip emoji: π colorFrom: gray colorTo: purple sdk: docker app_port: 7861 pinned: true license: mit secrets:
- name: HF_TOKEN description: Hugging Face API token for database backup.
- name: CLAUDE_CODE_OAUTH_TOKEN description: Anthropic Claude API key for Claude-powered agents.
- name: GEMINI_API_KEY description: Google Gemini API key for Gemini-powered agents.
- name: OPENAI_API_KEY description: OpenAI API key for GPT-powered agents.
- name: CLOUDFLARE_WORKERS_TOKEN description: "Cloudflare API token β auto-creates a Worker proxy and KeepAlive monitor."
Why HuggingClip?
Most AI agent platforms require expensive cloud servers or complex Kubernetes setups. HuggingClip runs the entire Paperclip platform on Hugging Face's free Docker Space tier (2 vCPU, 16GB RAM). No credit card, no server management, no Docker experience needed.
# One click to deploy β that's it.
# 1. Go to: https://huggingface.co/spaces/technicalboy2023/HuggingClip
# 2. Click "Duplicate this Space"
# 3. Add your API key
# Done. Your agents are running.
β¨ Features
| Category | Feature | What it means for you |
|---|---|---|
| π€ Multi-LLM | Claude, GPT, Gemini | Pick the best model per task β or use all three |
| β‘ One-click Deploy | Duplicate & run | No config, no CLI, no AWS β just a browser |
| πΎ Auto Persistence | HF Dataset backup | PostgreSQL auto-syncs to a private dataset β zero data loss on restart |
| π Live Dashboard | Real-time health monitor | See uptime, backup status, plugin count at a glance |
| π Cloudflare Proxy | Bypass network blocks | Automatically routes blocked APIs (Telegram, Discord, etc.) through Cloudflare |
| β° Keep-Awake Cron | Auto cron pings | Cloudflare Worker pings your Space every 10 minutes β prevents sleep |
| π Secure by Default | Auto secrets rotation | Randomized passwords, encrypted storage, non-root execution |
| π 100% HF-Native | Free tier friendly | Runs entirely on Hugging Face's free infrastructure |
π₯ Who Is This For?
| If you... | HuggingClip is for you |
|---|---|
| π€― Are tired of paying $20β$200/mo for AI agent hosting | β Free on HF Spaces |
| π§ Want to use Claude Code without a local machine | β Browser-based Claude Code |
| πΌ Need persistent agent workflows that survive restarts | β Auto backup to HF Dataset |
| π Want to connect agents to Telegram, Discord, email | β Built-in Cloudflare proxy |
| π Prefer Python for automation | β Runs any LLM, any agent |
| βοΈ Are new to Docker but want AI agents | β No Docker skills needed |
π Quick Start (3 Minutes)
Step 1: Duplicate the Space
Step 2: Add Your API Key
In your Space's Settings β Variables and secrets, add one (or more) of these:
| Secret | Provider | Get Your Key |
|---|---|---|
ANTHROPIC_API_KEY | Claude (Anthropic) | console.anthropic.com |
GEMINI_API_KEY | Gemini (Google) | ai.google.dev |
OPENAI_API_KEY | GPT (OpenAI) | platform.openai.com |
HF_TOKEN | Backup (HF Dataset) | huggingface.co/settings/tokens |
[!TIP] Always add
HF_TOKENfor database persistence. Without it, your agents, tasks, and conversations reset on every restart.
Step 3: Launch
The Space builds automatically (~60s). Open the Logs tab, wait for HuggingClip is ready!, then visit your Space URL.
Step 4: Create Admin Account
On first boot, the dashboard shows an admin invite URL. Click it β set up your account β start building agents.
π‘ Use Cases
- Personal AI Assistant Hub β One dashboard for Claude, GPT, and Gemini agents
- Code Review Automation β Claude Code reviews PRs, writes tests, refactors code
- Content Workflow β Gemini drafts, GPT edits, Claude publishes
- DevOps Agent β Monitor logs, restart services, respond to alerts
- Research Pipeline β Web research β summarization β report generation
- Social Media Bot β Auto-post to Telegram, Discord, Twitter via Cloudflare proxy
π Configuration Reference
Secrets (Set in HF Space Settings)
| Variable | Required? | Default | Description |
|---|---|---|---|
ANTHROPIC_API_KEY | No* | β | Claude API key β enables Claude Code agents |
GEMINI_API_KEY | No* | β | Google Gemini API key |
OPENAI_API_KEY | No* | β | OpenAI API key for GPT agents |
HF_TOKEN | No | β | HF write token β enables database backup persistence |
CLAUDE_CODE_OAUTH_TOKEN | No | β | Long-lived Claude OAuth token (1 year, no per-token cost) |
CLOUDFLARE_WORKERS_TOKEN | No | β | Auto-creates proxy + keep-awake workers |
*At least one LLM key required for agents to work.
Environment Variables
| Variable | Default | Description |
|---|---|---|
PAPERCLIP_DEPLOYMENT_MODE | authenticated | authenticated or local |
BACKUP_DATASET_NAME | huggingclip-backup | HF Dataset name for backups |
SYNC_INTERVAL | 3600 | Backup interval in seconds |
SYNC_MAX_FILE_BYTES | 52428800 | Max backup size (50MB) |
BETTER_AUTH_SECRET | auto-generated | Auth secret (auto-persisted) |
ποΈ Architecture
ββββββββββββββββ Port 7861 ββββββββββββββββββββ
β Browser β βββββββββββββββΊ β health-server.js β
β (Dashboard) β β (Dashboard + β
ββββββββββββββββ β Reverse Proxy) β
βββββββββ¬βββββββββββ
β proxy
βΌ
ββββββββββββββββββββ
β Paperclip App β Port 3100
β (Agent Engine) β
βββββββββ¬βββββββββββ
β
βββββββββββββββββββββββββΌββββββββββββββββββββββββ
βΌ βΌ βΌ
ββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββ
β PostgreSQL β β HF Dataset β β Cloudflare β
β (Embedded) βββββββΊβ (Backup/Restore) β β Worker(s) β
ββββββββββββββββ ββββββββββββββββββββ β (Proxy + β
β KeepAlive) β
ββββββββββββββββ
Startup Flow
1. Validate LLM keys ββΊ 2. Start PostgreSQL ββΊ 3. Restore backup from HF Dataset
4. Start sync loop βββΊ 5. Launch health server (7861) βββΊ 6. Generate config
7. Launch Paperclip (3100) βββΊ 8. Bootstrap admin βββΊ 9. Ready!
π οΈ Local Development
git clone https://github.com/technicalboy2023/spaceclip.git
cd spaceclip
cp .env.example .env
# Edit .env with your API keys
# Option A: Docker
docker build -t spaceclip .
docker run -p 7861:7861 -e HF_TOKEN=hf_xxxx spaceclip
# Option B: Docker Compose
docker-compose up -d
# Dashboard: http://localhost:7861/
π Cloudflare Integration (Optional)
Hugging Face Spaces blocks some outbound connections. HuggingClip auto-provisions Cloudflare Workers to solve this:
| Worker | Purpose | Cron |
|---|---|---|
| Proxy Worker | Routes blocked API traffic through Cloudflare | On-demand |
| KeepAlive Worker | Pings /health every 10 min to prevent Space sleep | */10 * * * * |
Setup: Add CLOUDFLARE_WORKERS_TOKEN as a Space secret. Everything else is automatic.
Proxied domains by default: Telegram, Discord, WhatsApp, Facebook, Twitter/X, LinkedIn, TikTok, Reddit, OpenAI, SendGrid, Google APIs.
π Troubleshooting
| Problem | Solution |
|---|---|
| β Agents don't run | Add at least one LLM API key to Space secrets |
| π Data lost on restart | Set HF_TOKEN β backup must run once before restart |
| π΄ Space keeps sleeping | Add CLOUDFLARE_WORKERS_TOKEN for auto keep-awake |
| β οΈ 502 errors on dashboard | Wait 60β90s for Paperclip to finish booting |
| π¦ Backup too large | Increase SYNC_MAX_FILE_BYTES or archive old agent runs |
| π’ Sync not running | Verify HF_TOKEN is valid and has write permissions |
π Project Status
Current: Active development β deploying Paperclip v1 on HF Spaces.
Planned:
- π Multi-Space federation
- π¦ Backup versioning
- π Prometheus/Grafana monitoring
- π³ Kubernetes manifests
β€οΈ Support
If SpaceClip saves you time, consider buying me a coffee!
USDT (BEP-20 β Binance Smart Chain)
0xe8b80722fc68c66248b68f31f3e4af9c126766bc
[!WARNING] Send USDT on BEP-20 network only. Other networks will result in permanent loss.
π Links
- Paperclip Docs β Platform documentation
- Paperclip GitHub β Upstream project
- HuggingFace Spaces β HF Spaces guide
- HF Token Setup β Get your API token
- Cloudflare API Tokens β For proxy + keep-awake
π€ Contributing
Contributions are welcome! Check CONTRIBUTING.md for guidelines.
π License
MIT β see LICENSE for details.
Made with β€οΈ by @technicalboy2023 for the Paperclip community.