convez.ai
Agente
technicalboy2023

spaceclip

technicalboy2023/spaceclip

Ver no GitHub
BomPluginScore Β· de 0 a 100

πŸš€ 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/spaceclip

1 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

Estrelas
1
Forks
0
Acompanhando
0
SaΓΊde
85%
Último commit
hΓ‘ 5 meses
VersΓ£o
β€”
Issues abertas
0
Contribuidores
2

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

CategoryFeatureWhat it means for you
πŸ€– Multi-LLMClaude, GPT, GeminiPick the best model per task β€” or use all three
⚑ One-click DeployDuplicate & runNo config, no CLI, no AWS β€” just a browser
πŸ’Ύ Auto PersistenceHF Dataset backupPostgreSQL auto-syncs to a private dataset β€” zero data loss on restart
πŸ“Š Live DashboardReal-time health monitorSee uptime, backup status, plugin count at a glance
🌐 Cloudflare ProxyBypass network blocksAutomatically routes blocked APIs (Telegram, Discord, etc.) through Cloudflare
⏰ Keep-Awake CronAuto cron pingsCloudflare Worker pings your Space every 10 minutes β€” prevents sleep
πŸ”’ Secure by DefaultAuto secrets rotationRandomized passwords, encrypted storage, non-root execution
🏠 100% HF-NativeFree tier friendlyRuns 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

Duplicate this Space

Step 2: Add Your API Key

In your Space's Settings β†’ Variables and secrets, add one (or more) of these:

SecretProviderGet Your Key
ANTHROPIC_API_KEYClaude (Anthropic)console.anthropic.com
GEMINI_API_KEYGemini (Google)ai.google.dev
OPENAI_API_KEYGPT (OpenAI)platform.openai.com
HF_TOKENBackup (HF Dataset)huggingface.co/settings/tokens

[!TIP] Always add HF_TOKEN for 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)

VariableRequired?DefaultDescription
ANTHROPIC_API_KEYNo*β€”Claude API key β€” enables Claude Code agents
GEMINI_API_KEYNo*β€”Google Gemini API key
OPENAI_API_KEYNo*β€”OpenAI API key for GPT agents
HF_TOKENNoβ€”HF write token β€” enables database backup persistence
CLAUDE_CODE_OAUTH_TOKENNoβ€”Long-lived Claude OAuth token (1 year, no per-token cost)
CLOUDFLARE_WORKERS_TOKENNoβ€”Auto-creates proxy + keep-awake workers

*At least one LLM key required for agents to work.

Environment Variables

VariableDefaultDescription
PAPERCLIP_DEPLOYMENT_MODEauthenticatedauthenticated or local
BACKUP_DATASET_NAMEhuggingclip-backupHF Dataset name for backups
SYNC_INTERVAL3600Backup interval in seconds
SYNC_MAX_FILE_BYTES52428800Max backup size (50MB)
BETTER_AUTH_SECRETauto-generatedAuth 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:

WorkerPurposeCron
Proxy WorkerRoutes blocked API traffic through CloudflareOn-demand
KeepAlive WorkerPings /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

ProblemSolution
❌ Agents don't runAdd at least one LLM API key to Space secrets
πŸ”„ Data lost on restartSet HF_TOKEN β€” backup must run once before restart
😴 Space keeps sleepingAdd CLOUDFLARE_WORKERS_TOKEN for auto keep-awake
⚠️ 502 errors on dashboardWait 60–90s for Paperclip to finish booting
πŸ“¦ Backup too largeIncrease SYNC_MAX_FILE_BYTES or archive old agent runs
🐒 Sync not runningVerify 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


🀝 Contributing

Contributions are welcome! Check CONTRIBUTING.md for guidelines.

πŸ“„ License

MIT β€” see LICENSE for details.

Made with ❀️ by @technicalboy2023 for the Paperclip community.

Ver o original no GitHub

Bom para

Relacionados