Per-Project Self-Hosted Convex Backend Provisioning Skill
Overview
A Claude Code skill that provisions an isolated, self-hosted Convex backend on demand for any app being scaffolded. One invocation allocates a dedicated deployment, its own Fly app, URL, and admin key, by talking to an internal control plane running on Cloudflare Workers.
Why It Exists
Apps that need a Convex backend (queries, mutations, actions, file storage, cron, auth) should not fall back to the hosted Convex cloud or require a developer to hand-run docker compose locally. This skill makes backend allocation a single, scriptable step inside an agentic build workflow, with one isolated deployment per project.
What We Built
A Bun-based TypeScript CLI (scripts/convex.ts) packaged as a Claude Code skill with a SKILL.md command index (provision, wait, destroy, and related lifecycle commands). It authenticates to the control plane via a bearer token supplied by the harness environment (never prompted, printed, or persisted), emits compact JSON on stdout for machine consumption, routes progress to stderr, and fails loudly with non-zero exit codes. Each provisioning call maps to exactly one Fly app and one isolated Convex deployment.
Technologies & Approach
TypeScript on Bun for fast, dependency-light execution; a Cloudflare Workers control plane as the single allocation authority; Fly.io as the per-deployment runtime host. The skill is declared with scoped allowed-tools (Bash/Read) and an argument hint so the agent can call it safely.
Outcome / Impact
Turns backend provisioning into a one-line, repeatable operation inside automated project scaffolding, giving every generated app its own isolated, self-hosted Convex instance without manual DevOps steps.
Capabilities Demonstrated
- Designing agent-callable infrastructure tooling (Claude Code skills)
- Self-hosted backend provisioning with per-project isolation
- Secure token handling and machine-readable CLI design
- Control-plane orchestration across Cloudflare Workers and Fly.io