# Supapool

> Supapool gives each parallel coding agent a full, isolated Supabase instance in 1 second, with real Postgres, Auth, and Storage — no mocks, no shared databases.

Supapool is a CLI tool and library that provisions ephemeral, isolated Supabase instances for parallel coding agents. Built by Kevin and Zach and backed by Y Combinator, it solves the problem of agents wiping each other's databases mid-run by giving every agent its own full Supabase stack — Postgres, Auth, and S3-compatible Storage — spun up in about one second.

## What It Is

Supapool is an infrastructure utility for AI coding agents that need real database environments rather than mocks. When multiple agents run concurrently, shared databases create race conditions and data corruption. Supapool wraps any shell command with `npx @supapool/cli run -- <command>`, leases a clean Supabase instance, injects its credentials into the process environment, and releases the instance when the command exits. The entire lifecycle is managed automatically.

## How the Lease Model Works

Every provisioned instance is a lease with a 30-minute TTL by default. The CLI renews the lease every 5 minutes while the wrapped command is alive. When the command exits — or if the process dies and renewals stop — the lease expires, the slot is wiped, and the instance returns to the pool. Nothing stored in an instance survives release, so every run is treated as fully disposable and ephemeral.

## What Gets Injected

The wrapped command receives a comprehensive set of environment variables covering all major frameworks and runtimes:
- Standard Supabase variables: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `DATABASE_URL`
- Public prefixes for Next.js, Vite, Astro, Svelte, Expo, Create React App, Gatsby, and Nuxt
- Prisma and Postgres URL aliases, and standard `PG*` connection variables
- `SUPAPOOL_INSTANCE_ID` to identify the lease

Secret keys are never assigned to browser-public variables.

## CLI and Library Interface

Supapool is intentionally CLI-only — there is no dashboard. Accounts, usage, and cost are exposed through the CLI and API, designed for agent ergonomics so output can be piped directly into automation pipelines. The npm package also exports a `withInstance` function for programmatic use, plus lifecycle primitives (`acquire`, `renew`, `release`, `startRenewer`) for code that manages its own lease boundaries. CI environments skip browser login by setting a `SUPAPOOL_API_KEY` environment variable from a stored secret.

## Why It Matters for Parallel Agent Workflows

Traditional Supabase branching can take minutes to create and bills as if branches were production instances. Supapool instances are ephemeral and colocated — they spin up close to where the agent is running rather than living in a fixed home region. Migrations from `supabase/migrations` are applied automatically in filename order on each run, so agents always start from a known schema state without touching production or modifying local environment files.

## Current Status

Supapool is currently in beta and is backed by Y Combinator. The service is free during the beta period. A system status page is available at status.supapool.io.

## Features
- Ephemeral isolated Supabase instances per agent
- Full Postgres, Auth, and S3-compatible Storage
- Spins up in ~1 second
- Automatic migration application from supabase/migrations
- Lease-based lifecycle with auto-renewal and auto-release
- Environment variable injection for all major frameworks (Next.js, Vite, Astro, Svelte, Expo, Gatsby, Nuxt)
- CLI and programmatic library API
- CI support via SUPAPOOL_API_KEY secret
- No dashboard — CLI and API only
- GitHub-based authentication
- withInstance, acquire, renew, release lifecycle primitives

## Integrations
Supabase, Postgres, GitHub (auth), Next.js, Vite, Astro, Svelte, Expo, Create React App, Gatsby, Nuxt, Prisma, npm/npx, pnpm

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://supapool.io
- Documentation: https://supapool.io
- Repository: https://www.npmjs.com/package/@supapool/cli
- EveryDev.ai: https://www.everydev.ai/tools/supapool