Supapool: Ephemeral Supabase Instances for Parallel Coding Agents

Supapool allows developers and AI agents to lease clean, isolated Supabase instances in approximately 400ms. This eliminates the need for mocks or slow database branching, ensuring that parallel coding agents can run migrations and execute database operations against a real Supabase stack without interfering with one another.

Rapid Deployment of Isolated Supabase Stacks

Supapool provides a real Supabase environment—including Postgres, Auth, and S3-compatible Storage—that is colocated close to where the agent is executing work. Unlike standard database branching, which can take minutes to initialize and incur production-level billing, Supapool instances are ephemeral and designed for high-speed acquisition.

Key technical advantages include:

  • Zero Collision: Parallel agents operate in entirely separate instances, preventing them from wiping each other's data mid-run.
  • No Mocks: Testing occurs against a real stack, ensuring migrations and database operations are validated against actual Supabase infrastructure.
  • Colocation: Instances are spun up near the agent's execution environment to minimize latency.
  • Agent-First Design: The platform is CLI-only with no dashboard, allowing accounts, usage, and costs to be piped directly into automated systems via API.

CLI Integration and Workflow

Supapool is primarily managed via the @supapool/cli package. The core workflow involves wrapping existing commands to inject a temporary environment.

Command Execution

Using the run command, Supapool leases an instance and injects the necessary credentials into the environment variables of the wrapped command:

npx @supapool/cli run -- npm run dev

When run is executed, the CLI performs the following sequence:

  1. Acquires a clean instance.
  2. Applies all .sql files found in supabase/migrations in filename order.
  3. Starts the command with the instance credentials in its environment.
  4. Renews the lease while the command remains active.
  5. Releases the instance upon command exit.

Environment Variable Injection

The wrapped command receives standard Supabase variables, including SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, and DATABASE_URL. To ensure compatibility with various frameworks, these values are mirrored to common public prefixes used by Next.js, Vite, Astro, Svelte, Expo, Create React App, Gatsby, and Nuxt, as well as Prisma and Postgres URL aliases.

Lease Management and Lifecycle

Every Supapool instance is as a lease with a default Time-to-Live (TTL) of 30 minutes. The CLI automatically renews the lease every 5 minutes while the process is active. If the process terminates or the renewal heartbeat stops, the lease expires and the instance is wiped and returned to the pool.

Because instances are disposable, no data persists after the lease is released.

CI/CD and Programmatic Access

Supapool supports automated environments through the SUPAPOOL_API_KEY environment variable. In CI environments, users can copy their API key from ~/.config/supapool/config.json and set it as a secret to bypass browser-based GitHub login.

SUPAPOOL_API_KEY=sp_live_... npx @supapool/cli run -- pnpm test

For developers needing deeper integration, the @supapool/cli npm package can be used as a library. The withInstance function manages the lease lifecycle automatically:

import { withInstance } from '@supapool/cli'

await withInstance(async (instance) => {
  const { SUPABASE_URL, SUPABASE_ANON_KEY, DATABASE_URL } = instance.env
  // execute tests or seed data
})

Advanced users can utilize the exported lifecycle primitives acquire, renew, release, and startRenewer for custom lease boundary management.

Sources