Clawfy

Grab your Claw in seconds. One-click hosting for OpenClaw AI agents — deploy to Telegram, Discord, or WhatsApp without ever touching SSH, Docker, or a CLI.

_{▶︎ Watch the 60-second demo — pick a model, pick a channel, deploy.}

---

Clawfy is a complete, production-ready, one-click deployment platform for AI agents, built on OpenClaw. Pick a model, pick a channel, deploy — the agent is live in seconds. Under the hood: per-agent VM isolation, multi-model routing, and real-time usage-based billing. Server provisioning, API keys, and billing are all handled for you — pay only for what you use.

Think "SimpleClaw, but open source" — with credit-based pay-as-you-go billing, a warm server pool for near-instant deploys, and platform-managed API keys (no BYOK required).

✨ Features

• 🚀 One-click deploy — model + platform + token → live bot. No SSH, Docker, or CLI.
• 💬 Multi-channel — Telegram, Discord, and WhatsApp out of the box.
• ⚡ Near-instant provisioning — a warm server pool claims a pre-built machine in ~3s; on-demand falls back to ~30–60s.
• 💳 Pay-as-you-go billing — Stripe one-time credit purchases, real-time per-token deduction (no subscriptions).
• 🔑 Platform-managed keys — OpenRouter / LiteLLM keys are provisioned per user; end users never bring their own.
• 🧩 280+ workflow templates — ready-made agent personas across engineering, ops, support, and more.
• 🛰️ Self-healing infra — hourly billing cron + 5-min pool replenishment, with Discord alerts on every state change.
• 🌍 i18n — English + 中文 built in via next-intl.

🧱 Tech Stack

Layer	Choice
Frontend	Next.js 16 (App Router) · TypeScript · Tailwind CSS
Auth & DB	Supabase (Google OAuth · PostgreSQL · RLS)
Payments	Stripe (one-time credit purchases)
Servers	Hetzner Cloud API (golden-snapshot provisioning + SSH config injection)
AI providers	OpenRouter / LiteLLM (platform-managed keys)
Scheduling	Vercel Cron or server-side cron
Deploy target	Vercel or Docker (output: "standalone")

📑 Table of Contents

• Quick Start
• How It Works
• Pricing Model
• Self-Hosting
• Environment Variables
• Project Structure
• Contributing
• License

🚀 Quick Start (Local Dev)

git clone https://github.com/ucfyao/clawfy.git
cd clawfy
npm install
cp .env.example .env      # fill in your keys — see Environment Variables below
npm run dev               # http://localhost:3000

Forward Stripe webhooks while developing:

npm run stripe:listen

You can run the app locally with just Supabase + Stripe keys. Hetzner / AI-provider keys are only needed once you want to actually provision agent servers.

🔍 How It Works

A deploy walks through balance check → key provisioning → server claim → config injection:

POST /api/instances
  → validate balance ≥ monthly fee
  → provision OpenRouter key (ensureUserKey)
  → pre-deduct monthly fee
  → insert instance (status: provisioning)
  → pool path:    claim warm server → SSH inject .env → docker compose restart  (~3s)
    on-demand:    Hetzner create from snapshot → poll SSH → inject config        (~30–60s)
  → status: running

Two cron jobs keep the platform healthy:

Cron	Frequency	Job
usage-sync	hourly	renew billing periods, stop zero-balance instances, emit balance warnings
pool-check	every 5 min	promote ready servers → available, replenish pool, time out stuck servers

Per-message token usage is proxied through /api/chat → OpenRouter with a 1.5× markup and deducted in real time via an atomic increment_balance RPC.

📖 Full architecture, API routes, DB schema, and end-to-end flows: docs/architecture.md.

💳 Pricing Model

The reference pricing shipped with the app (fully configurable in src/types):

Credit packages

Package	Price	Credits	Bonus
Starter	$20	2,000	—
Power	$100	12,000	+2,000
Pro	$200	25,000	+5,000
Custom	$20–$1,000	100 cr/$	—

Machine monthly cost

Size	Specs	Credits/mo
Small	2 vCPU / 2 GB	650
Medium	2 vCPU / 4 GB	1,150
Large	4 vCPU / 8 GB	2,700

1 credit ≈ $0.01 · credits never expire · no refund on early stop · restart within a billing period is free.

🛠️ Self-Hosting

1. Supabase

1. Create a project at supabase.com.
2. SQL Editor → run every migration in supabase/migrations/ in order (001_initial.sql … and onward).
3. Authentication → Providers → enable Google OAuth.
4. Copy the Project URL, Anon Key, and Service Role Key.

2. Stripe

1. Create an account at stripe.com.
2. No products needed — credit packages use dynamic pricing.
3. Developers → Webhooks → add endpoint https://clawfy.io/api/stripe/webhook.
4. Subscribe to the checkout.session.completed event.
5. Copy the Secret Key, Publishable Key, and Webhook Signing Secret.

3. Hetzner

1. Create an account at hetzner.cloud.
2. Security → API Tokens → generate one with Read & Write.
3. Security → SSH Keys → add your public key and note its ID.
4. Copy the API Token and SSH Key ID.

4. AI provider (OpenRouter or LiteLLM)

• OpenRouter — get a provisioning key from openrouter.ai for key CRUD (not a regular API key).
• LiteLLM — stand up a LiteLLM proxy, then copy its URL and master key.

5. Golden snapshot (required for fast deploys)

# Needs: HETZNER_API_TOKEN, HETZNER_SSH_KEY_ID, ~/.ssh/id_ed25519, jq
./scripts/create-snapshot.sh
# → outputs a Snapshot ID; set it as HETZNER_SNAPSHOT_ID

The snapshot bakes in Ubuntu 24.04 + Docker + a pre-pulled OpenClaw image and helper scripts, so servers boot ready-to-run. Deploy time only injects a user-specific .env.

6. Server pool (optional — near-instant deploys)

1. Set SERVER_POOL_SIZE=2 (or your desired warm count).
2. The pool-check cron creates servers as initializing, promotes them to available once SSH is reachable, and times out stuck ones (>15 min).
3. Manual trigger: curl -H "Authorization: Bearer $CRON_SECRET" $APP_URL/api/cron/pool-check.

Pool servers cost money while idle — only enable for expected traffic.

7. Cron setup

# scripts/crontab.example has the full reference
0   * * * * curl -s -H "Authorization: Bearer $CRON_SECRET" https://clawfy.io/api/cron/usage-sync  > /dev/null 2>&1
*/5 * * * * curl -s -H "Authorization: Bearer $CRON_SECRET" https://clawfy.io/api/cron/pool-check  > /dev/null 2>&1

On Vercel, configure both endpoints in vercel.json with their schedules.

Deploy

npx vercel        # Option A: Vercel
docker compose up -d   # Option B: Docker

⚙️ Environment Variables

Copy .env.example to .env and fill in:

Variable	Source
NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY	Supabase → Settings → API
STRIPE_SECRET_KEY / NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY	Stripe → Developers → API keys
STRIPE_WEBHOOK_SECRET	Stripe → Developers → Webhooks
HETZNER_API_TOKEN / HETZNER_SSH_KEY_ID	Hetzner → Security
SSH_PRIVATE_KEY	Your ed25519 private key (literal \n for newlines)
HETZNER_SNAPSHOT_ID	Output of scripts/create-snapshot.sh
AI_PROVIDER	openrouter or litellm
OPENROUTER_PROVISIONING_KEY	OpenRouter (if using OpenRouter)
LITELLM_PROXY_URL / LITELLM_MASTER_KEY	LiteLLM (if using LiteLLM)
CRON_SECRET	openssl rand -hex 32
NEXT_PUBLIC_APP_URL	Your domain URL (e.g. https://clawfy.io)
DISCORD_WEBHOOK_URL	Optional — admin alerts

📂 Project Structure

Expand directory tree

scripts/
├── create-snapshot.sh   # Build the Hetzner golden snapshot (Docker + OpenClaw)
├── crontab.example      # Crontab reference for billing + pool jobs
├── replenish-pool.sh    # Legacy server-side cron wrapper
└── setup.sh             # Guided env setup

src/
├── app/
│   ├── [locale]/        # Public, i18n pages (landing, pricing, docs, auth)
│   ├── dashboard/       # Deploy wizard, instances, billing, settings
│   └── api/
│       ├── instances/   # Instance CRUD + status/configure/pairing/health
│       ├── chat/        # AI chat proxy (real-time token billing)
│       ├── cron/        # usage-sync (billing) + pool-check (pool mgmt)
│       ├── stripe/      # checkout + webhook
│       ├── v1/chat/completions/  # OpenAI-compatible proxy
│       └── admin/       # Admin routes
├── components/          # shared/ (Navbar, Footer) + dashboard/
├── lib/
│   ├── supabase/        # browser + server + service clients
│   ├── hetzner.ts       # Hetzner Cloud API client
│   ├── ai-provider.ts   # OpenRouter / LiteLLM factory
│   ├── ssh.ts           # injectConfig, pairing, agent control
│   └── provisioning.ts  # pool claim, on-demand create, failure handling
├── content/personas/    # 280+ workflow templates
└── types/               # Shared types + MACHINES constant

🧑‍💻 Available Commands

npm run dev            # dev server (localhost:3000)
npm run build          # production build
npm run lint           # ESLint
npm run stripe:listen  # forward Stripe webhooks to localhost
npm run db:migrate     # push schema to Supabase
npm run db:reset       # reset Supabase database

🤝 Contributing

Contributions are welcome! To get started:

1. Fork the repo and create a branch (feat/your-feature or fix/your-bug).
2. Make your changes and run npm run lint + npm run build.
3. Use Conventional Commits (feat:, fix:, docs:, …).
4. Open a PR against main with a clear description.

📖 Full guide, dev setup, and conventions → CONTRIBUTING.md. Found a bug or have an idea? Open an issue.

🔒 Security

Found a vulnerability? Please do not open a public issue. See our Security Policy for private disclosure instructions.

🙏 Acknowledgements

• OpenClaw — the AI agent runtime Clawfy hosts.
• Next.js, Supabase, Stripe, and Hetzner Cloud — the backbone of the platform.

📄 License

MIT © Clawfy Contributors