Ship a web app to production for $0/month on Vercel + Render + Supabase + Upstash free tiers. A Claude Code / Agent Skill (also a human-readable playbook) with every gotcha documented — Hobby cron limits, Blueprint env-loss,
supabase db push5432 timeout, ClipboardEvent paste trick, Vercel CLIMust not contain "***"in CI, and 20+ more.
git clone https://github.com/sunrf-renlab-ai/zero-cost-deploy ~/.claude/skills/zero-cost-deployClaude Code auto-discovers it. Next time you say "deploy this" / "ship to prod" / "免费上线", the skill activates. Works in Cursor, Cline, Continue, OpenClaw, and any agent that follows the Agent Skills spec.
You're hitting any of these — or about to wire a fresh free-tier prod stack first time:
- 🟥
Hobby accounts are limited to daily cron jobs— Vercel rejects your deploy - 🟥
tls error (EOF)onsupabase db push(Clash/Mihomo fakeip blocks port 5432) - 🟥
Error: must not contain "***"— Vercel CLI in GitHub Actions - 🟥
Authorization header is badly formatted— GitHub MCP refusing to connect - 🟥 Render Blueprint apply completes, then service crashes on missing env
- 🟥 GitHub OAuth Authorize button stays disabled 2-4 s after page load; JS clicks ignored
- 🟥
sb_publishable_*rejected by older@supabase/supabase-js - 🟥 Vercel env paste form swallows your values when scripted
…or the broader "I want to deploy free but every tutorial handwaves the broken parts."
- ✅ $0/month — Vercel Hobby + Render Free + Supabase Free + Upstash Free + GitHub Actions
- ✅ MCP-first — uses Supabase / Vercel / GitHub MCP tools by default; HTTPS Management API fallback for Render + Upstash (no MCP yet)
- ✅ Pre-flight self-install — detects missing CLIs/MCP plugins and installs them (
claude plugin install …,brew install …,gh auth login) - ✅ Real gotchas, real fixes — every entry in
references/gotchas.mdis a documented "lost an hour to this" moment with the actual error string + workaround - ✅ Reproducible — secrets generation script, smoke test script, secret rotation playbook, render.yaml + Dockerfile + workflows templates
End-to-end first deploy: ~10 minutes once you have the API keys.
| Service | Role | Cap | MCP |
|---|---|---|---|
| Supabase Free | Postgres + Auth + RLS + Storage | 500 MB DB · 50K MAU · pauses 7d idle | ✅ official |
| Vercel Hobby | Frontend + short API + daily cron | 100 GB BW · 60 s timeout · daily-only cron · no commercial | ✅ (env vars not exposed) |
| Render Free | Long-running, WebSocket, > 60 s, Docker | 512 MB RAM · sleeps 15 min · 750 hr/mo | ❌ — HTTPS API |
| Upstash Free | Redis (rate-limit, locks, ephemeral state) | 10K cmd/day · 256 MB | ❌ — HTTPS REST |
| GitHub Actions | CI + sub-daily crons | Unlimited on public repos | ✅ |
| Sentry Free (opt) | Errors + sourcemaps | 5K errors/month | — |
Monthly bill: $0. Optional custom domain: ~$10/year.
Every "deploy your app for free" guide handwaves the broken parts. They tell you to click the deploy button — they don't tell you:
- Vercel Hobby blocks sub-daily crons after you've designed your whole app around them
- Render Blueprint silently saves empty env vars — service crashloops on boot
- Clash/Mihomo TUN fakeip (
198.18.0.0/15) breaks raw TCP to Supabase Postgres on port 5432 - GitHub's OAuth Authorize button has a 2-4 s anti-bot disable window; JS clicks during it are silently ignored
- Vercel CLI in Actions dies with
Must not contain "***"when a trailing\nin the secret triggers GitHub's redaction regex to eat--in the command line - The 2026
sb_publishable_*/sb_secret_*key format breaks@supabase/supabase-js< 2.x - Render Postgres free tier deletes itself after 90 days (use Supabase instead)
- Custom domain stuck at "Verification Needed" when there's a conflicting A/AAAA record at the same name
- SSL cert never provisions because of CAA records blocking Let's Encrypt
Each gotcha in references/gotchas.md is a real "I lost an hour to this" moment with the exact symptom + working fix.
- MCP > Management API > UI automation. Use MCP tools where they exist; fall back to bare HTTPS API; touch UIs only when unavoidable.
- ClipboardEvent for paste-aware React forms. The one synthetic event React's value tracker accepts (Vercel env vars).
- OAuth identity vs GitHub App permissions are different things. Render and Vercel both have this split; conflating them is the #1 "no repos found" cause.
- Network-aware fallbacks for TUN proxies. Clash / Mihomo / corporate firewalls break raw TCP. Use HTTPS Management APIs.
- Anti-bot delays are real. GitHub OAuth Authorize, hCaptcha, Stripe — don't fight them, fall back to manual click.
zero-cost-deploy/
├── SKILL.md # entry point — 334-line dense playbook
├── references/
│ ├── mcp-tools.md # MCP tool catalog per service + curl fallbacks
│ ├── supabase.md # Management API, RLS, project pausing, key formats
│ ├── upstash.md # Region selection, REST API, rate-limit pattern
│ ├── render.md # Blueprint quirks, Dockerfile patterns, cold starts
│ ├── vercel.md # Hobby limits, env paste trick, Edge vs Node, custom domain, GH Actions CI deploy
│ ├── management-apis.md # REST surface for every service
│ ├── browser-fallbacks.md # Last-resort UI scripting (rare, mostly "don't")
│ └── gotchas.md # Real-world breakage catalog with literal error strings
├── scripts/
│ ├── gen-secrets.sh # generate randoms (RPC token, CRON_SECRET, AES key, …)
│ ├── supabase-push-migration.sh # push SQL via HTTPS Management API
│ ├── supabase-verify-tables.sh # confirm tables + RLS landed
│ ├── upstash-create-redis.sh # create Redis DB without fighting the UI
│ ├── verify-deploy.sh # smoke-test a fresh deploy
│ ├── vercel-add-domain.sh # add custom domain + poll verification
│ └── rotate-secrets.md # rotation checklist
└── templates/
├── render.yaml Dockerfile vercel.json .env.example
└── workflows/{ci,scheduled}.yml # GH Actions: CI + sub-daily crons
- Sub-second cold start required (Render Free sleeps; 30–60 s wake)
- Commercial monetization on Vercel Hobby (banned by ToS — use Cloudflare Pages)
- Postgres > 500 MB or > 50K MAU (Supabase Pro $25/mo)
- Heavy compute > 512 MB RAM (Render Starter $7/mo or Cloudflare Workers for stateless)
- Multi-region writes (everything here is single-region on free)
- HIPAA / SOC2 — free tiers don't sign BAAs
Same git clone. Then:
| Client | How |
|---|---|
| Claude Code | clone into ~/.claude/skills/ — auto-discovered |
| Cursor | symlink the dir into Cursor's rules path, or @-mention SKILL.md |
| Cline / Continue | point the client's instruction file at SKILL.md |
| OpenClaw / Codex CLI | follows Agent Skills spec — drop into their skills dir |
The skill body references MCP tools (mcp__plugin_supabase_supabase__*, mcp__plugin_vercel_vercel__*, etc.) — install the equivalent MCP servers in your client. Fallback paths use plain curl and standard CLIs, so it degrades gracefully without MCP.
Hit a gotcha that isn't documented? Open a PR adding it to references/gotchas.md.
The bar: every entry must be a real issue you (or someone you trust) actually hit. No theoretical "what if X happens" — only "X happened on date Y, here's the exact symptom and the fix."
- agentskills.io — Agent Skills spec
- anthropics/skills — official Anthropic skills
- VoltAgent/awesome-agent-skills — curated cross-agent skill list
- hesreallyhim/awesome-claude-code — Claude Code resources
For discoverability: claude code skill · claude code plugin · agent skill · MCP server · zero cost deploy · free tier deploy · vercel hobby · vercel render supabase · supabase upstash redis · 免费上线 · 零成本部署 · vercel 免费 · supabase 免费 · render 免费 · how to deploy free 2026 · indie hacker stack · side project deploy · serverless deploy free · self host alternative · clash mihomo fakeip 5432 · vercel cron limit workaround · render blueprint env empty fix · supabase 5432 timeout fix · vercel CLI must not contain · github mcp authorization header badly formatted
MIT. See LICENSE.