# AGENTS.md — Build guide for Supabase Pro

## Project scope
Deploy the documented self-hosted Supabase stack for one private application, configure auth callbacks and storage policies and record a complete backup/restore procedure. Use upstream services instead of writing a new auth/storage control plane.

Catalogue verdict: kinda. The core loop is buildable, but a dependable replacement becomes a real weekend or multi-day project. For Supabase Pro, self-host a Postgres backend with auth, storage, and a small API surface. The hard boundary is managed postgres, backups, auth delivery, storage, edge functions, observability, and support, plus infrastructure scale, operations, and reliability.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. Read the current official self-hosting guide and use a pinned upstream release. This requires operating the database, auth, storage and routing services, not just a PostgreSQL container.
- Implementation components: Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.
- Scope boundary: Managed backups, cloud dashboard parity and operational service guarantees remain outside the self-hosted build.

## Stack and architecture
- Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes.
- Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.
- Operating records: official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests

## Security and data integrity
- Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Enable RLS for exposed application tables and add ownership/membership policies. Keep service-role/secret keys server-side, configure storage access policies and review privileged views/functions.
- Correctness boundary: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
- Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
- Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point.

## Agent implementation rules
- Project rule — operating records: official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests
- Project rule — preserve this invariant: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
- Project rule — acceptance evidence: An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files.

## Optional agent skills and references
- Optional external skill: [supabase-postgres-best-practices](https://github.com/supabase/agent-skills/blob/main/skills/supabase-postgres-best-practices/SKILL.md) — Review PostgreSQL schemas, queries, indexes, pooling, concurrency and row-level security. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate the actual Supabase Pro-inspired workflow with owned or clearly labeled sample data: Deploy the documented self-hosted Supabase stack for one private application, configure auth callbacks and storage policies and record a complete backup/restore procedure. Use upstream services instead of writing a new auth/storage control plane.
- Publish a reproducible walkthrough with this observable result: An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Managed backups, cloud dashboard parity and operational service guarantees remain outside the self-hosted build. Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Select and document the upstream release. Deploy the documented self-hosted Supabase stack for one private application, configure auth callbacks and storage policies and record a complete backup/restore procedure. Use upstream services instead of writing a new auth/storage control plane. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Managed backups, cloud dashboard parity and operational service guarantees remain outside the self-hosted build.
2. Phase 2 — Configure the maintained application. Record official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Enable RLS for exposed application tables and add ownership/membership policies. Keep service-role/secret keys server-side, configure storage access policies and review privileged views/functions. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate.
5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files.
6. Phase 6 — Operator handoff and acceptance. An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting.

## Paid-product capabilities outside this build
- managed Postgres, backups, auth delivery, storage, edge functions, observability, and support
- global edge network
- managed databases
- autoscaling
- DDoS protection, support, and compliance

## Implementation prompt
WORKING SLICE
Deploy the documented self-hosted Supabase stack for one private application, configure auth callbacks and storage policies and record a complete backup/restore procedure. Use upstream services instead of writing a new auth/storage control plane.

Operate this scoped Supabase Pro-inspired deployment through the maintained upstream application. Record its configuration and failure states; do not rebuild its schema, interface or services.

Architecture
- Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes.
- Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.

Prerequisites and limits
A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing. Read the current official self-hosting guide and use a pinned upstream release. This requires operating the database, auth, storage and routing services, not just a PostgreSQL container.
Outside this release: Managed backups, cloud dashboard parity and operational service guarantees remain outside the self-hosted build.

Configuration and correctness
official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests
Invariant: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.

Security and privacy
Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Enable RLS for exposed application tables and add ownership/membership policies. Keep service-role/secret keys server-side, configure storage access policies and review privileged views/functions.

Recovery and export
Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point.

Implementation order
1. Phase 1 — Select and document the upstream release. Deploy the documented self-hosted Supabase stack for one private application, configure auth callbacks and storage policies and record a complete backup/restore procedure. Use upstream services instead of writing a new auth/storage control plane. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Managed backups, cloud dashboard parity and operational service guarantees remain outside the self-hosted build.
2. Phase 2 — Configure the maintained application. Record official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Enable RLS for exposed application tables and add ownership/membership policies. Keep service-role/secret keys server-side, configure storage access policies and review privileged views/functions. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate.
5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files.
6. Phase 6 — Operator handoff and acceptance. An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting.

Acceptance
An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [supabase-postgres-best-practices](https://github.com/supabase/agent-skills/blob/main/skills/supabase-postgres-best-practices/SKILL.md) — Review PostgreSQL schemas, queries, indexes, pooling, concurrency and row-level security. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — operating records: official self-hosted Supabase service configuration, database roles, auth settings, storage volumes and backup manifests
Project rule — preserve this invariant: Default secrets must be replaced; public API keys do not replace authorization policies and privileged service credentials never enter client bundles.
Project rule — acceptance evidence: An unauthenticated client cannot read a protected table or object; restoring isolated volumes recovers both database rows and stored files.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.