> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Supabase projects and databases from Guild agents

> Connect Guild agents to Supabase to manage projects, run queries, handle migrations, deploy functions, and control auth config using governed credentials.

Integrations · Supabase

A Guild agent can provision Supabase projects, execute database queries, and manage auth configuration on your team's behalf. Guild stores the personal access token server-side and injects it into every request without exposing it to the agent. Credential policies let you restrict which operations each agent may call, and every request is auditable through Guild's credential proxy.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Supabase.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Supabase to your first agent.

## What the Supabase integration exposes

The integration provides tools that cover project and organization management, database branching, SQL migration lifecycle, edge function deployment, secret management, auth service configuration, and backup and restore operations. Tools follow the naming convention supabase\_v1\_ and are imported from the guildai\~supabase package. Use pick() to give an agent only the tools it needs.

## How it works

**1. Open credentials in Guild**

Go to Access & setup > Credentials in your Guild account or organization. This page lists connected credentials and the integrations available to connect.

**2. Connect your Supabase token**

Click Connect, select supabase, and paste your Supabase personal access token into the API Key field. Guild sends it as a bearer token in the Authorization header on every request.

**3. Import tools into your agent**

Import SupabaseTools from @guildai-services/guildai\~supabase and spread it into your agent's tools object. Use pick() to include only the specific supabase\_v1\_ tools your agent requires.

## Why Supabase access needs governing

Supabase tools can create or delete projects, apply and roll back SQL migrations, deploy edge functions, rotate API keys, and modify auth configuration. A credential scoped to the account grants wide reach by default. Guild's credential policies let you write ALLOW and DENY rules that the credential proxy enforces before any request leaves Guild, limiting an agent to specific operations or HTTP methods without changing the underlying token.

Credentials can be scoped to a workspace, a single member, or a dedicated agent so the right token is used in each context. Guild injects the token server-side after the policy check passes; agent code never sees it. If no rule allows a request, Guild denies it. You can delete the auto-created allow-all policy to enforce an explicit deny-by-default posture once your rules cover everything agents need.

## About the Supabase integration

Agents can create and manage Supabase projects, organizations, and database branches. They can run SQL migrations, deploy edge functions, and manage secrets and auth configuration. Access is established using a Supabase personal access token. The integration is `guildai~supabase`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Supabase**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **supabase**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { SupabaseTools } from "@guildai-services/guildai~supabase"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Supabase.",
  tools: { ...SupabaseTools },
})
```

### Selecting specific tools

Tools are named with the `supabase_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~supabase`:

> [accordion] All 170 tools
>
> | Tool | What it does |
> | - | - |
> | `supabase_v1_accept_invite_external_jit_access` | Accepts the invitation to JIT database access |
> | `supabase_v1_activate_custom_hostname` | This is an experimental endpoint. |
> | `supabase_v1_activate_vanity_subdomain_config` | This is an experimental endpoint. |
> | `supabase_v1_apply_a_migration` | Apply a migration. |
> | `supabase_v1_apply_project_addon` | Selects an addon variant, for example scaling the project’s compute instance up or down, and applies it to the project. |
> | `supabase_v1_authorize_jit_access` | Authorizes the request to assume a role in the project database |
> | `supabase_v1_authorize_user` | This is an experimental endpoint. |
> | `supabase_v1_bulk_create_secrets` | Creates multiple secrets and adds them to the specified project. |
> | `supabase_v1_bulk_delete_secrets` | Deletes all secrets with the given names from the specified project |
> | `supabase_v1_bulk_update_functions` | Bulk update functions. |
> | `supabase_v1_cancel_a_project_restoration` | Cancel a project restoration. |
> | `supabase_v1_check_vanity_subdomain_availability` | This is an experimental endpoint. |
> | `supabase_v1_claim_project_for_organization` | Claim project for organization. |
> | `supabase_v1_create_a_branch` | Creates a database branch from the specified project. |
> | `supabase_v1_create_a_function` | This endpoint is deprecated - use the deploy endpoint. |
> | `supabase_v1_create_an_organization` | Create an organization. |
> | `supabase_v1_create_a_project` | Create a project. |
> | `supabase_v1_create_a_sso_provider` | Create a sso provider. |
> | `supabase_v1_create_legacy_signing_key` | Create legacy signing key. |
> | `supabase_v1_create_login_role` | This is an experimental endpoint. |
> | `supabase_v1_create_project_api_key` | Create project api key. |
> | `supabase_v1_create_project_claim_token` | Create project claim token. |
> | `supabase_v1_create_project_signing_key` | Create project signing key. |
> | `supabase_v1_create_project_tpa_integration` | Create project tpa integration. |
> | `supabase_v1_create_restore_point` | Create restore point. |
> | `supabase_v1_deactivate_vanity_subdomain_config` | This is an experimental endpoint. |
> | `supabase_v1_delete_a_branch` | Deletes the specified database branch. |
> | `supabase_v1_delete_a_function` | Deletes a function with the specified slug from the specified project. |
> | `supabase_v1_delete_a_project` | Delete a project. |
> | `supabase_v1_delete_a_sso_provider` | Delete a sso provider. |
> | `supabase_v1_delete_hostname_config` | This is an experimental endpoint. |
> | `supabase_v1_delete_invite_external_jit_access` | Revokes and deletes the invitation |
> | `supabase_v1_delete_jit_access` | Remove JIT mappings of a user, revoking all JIT database access |
> | `supabase_v1_delete_login_roles` | This is an experimental endpoint. |
> | `supabase_v1_delete_network_bans` | This is an experimental endpoint. |
> | `supabase_v1_delete_project_api_key` | Delete project api key. |
> | `supabase_v1_delete_project_claim_token` | Delete project claim token. |
> | `supabase_v1_delete_project_tpa_integration` | Delete project tpa integration. |
> | `supabase_v1_deploy_a_function` | A new endpoint to deploy functions. |
> | `supabase_v1_diff_a_branch` | Diffs the specified database branch |
> | `supabase_v1_disable_preview_branching` | Disables preview branching for the specified project |
> | `supabase_v1_disable_readonly_mode_temporarily` | Disable readonly mode temporarily. |
> | `supabase_v1_enable_database_webhook` | This is an experimental endpoint. |
> | `supabase_v1_exchange_oauth_token` | Supports 'authorization\_code', 'refresh\_token', and 'urn:ietf:params:oauth:grant-type:jwt-bearer' grant types. |
> | `supabase_v1_generate_typescript_types` | Returns the TypeScript types of your schema for use with supabase-js. |
> | `supabase_v1_get_a_branch` | Fetches the specified database branch by its name. |
> | `supabase_v1_get_a_branch_config` | Fetches configurations of the specified database branch |
> | `supabase_v1_get_action_run` | Returns the current status of the specified action run. |
> | `supabase_v1_get_action_run_logs` | Returns the logs from the specified action run. |
> | `supabase_v1_get_a_function` | Retrieves a function with the specified slug and project. |
> | `supabase_v1_get_a_function_body` | Retrieves a function body for the specified slug and project. |
> | `supabase_v1_get_all_projects_for_organization` | Returns a paginated list of projects for the specified organization. |
> | `supabase_v1_get_a_migration` | Get a migration. |
> | `supabase_v1_get_an_organization` | Get an organization. |
> | `supabase_v1_get_a_snippet` | Get a snippet. |
> | `supabase_v1_get_a_sso_provider` | Get a sso provider. |
> | `supabase_v1_get_auth_service_config` | Get auth service config. |
> | `supabase_v1_get_available_regions` | This is an experimental endpoint. |
> | `supabase_v1_get_backup_schedule` | Get backup schedule. |
> | `supabase_v1_get_database_disk` | Get database disk. |
> | `supabase_v1_get_database_metadata` | This is an experimental endpoint. |
> | `supabase_v1_get_database_openapi` | Returns the PostgREST OpenAPI specification for the project. |
> | `supabase_v1_get_disk_utilization` | Get disk utilization. |
> | `supabase_v1_get_hostname_config` | This is an experimental endpoint. |
> | `supabase_v1_get_jit_access` | Mappings of roles a user can assume in the project database |
> | `supabase_v1_get_jit_access_config` | This is an experimental endpoint. |
> | `supabase_v1_get_legacy_signing_key` | Get legacy signing key. |
> | `supabase_v1_get_network_restrictions` | This is an experimental endpoint. |
> | `supabase_v1_get_organization_entitlements` | Returns the entitlements available to the organization based on their plan and any overrides. |
> | `supabase_v1_get_organization_project_claim` | Get organization project claim. |
> | `supabase_v1_get_performance_advisors` | This is an experimental endpoint. |
> | `supabase_v1_get_pgsodium_config` | This is an experimental endpoint. |
> | `supabase_v1_get_pooler_config` | Get pooler config. |
> | `supabase_v1_get_postgres_config` | Get postgres config. |
> | `supabase_v1_get_postgrest_service_config` | Get postgrest service config. |
> | `supabase_v1_get_postgres_upgrade_eligibility` | This is an experimental endpoint. |
> | `supabase_v1_get_postgres_upgrade_status` | This is an experimental endpoint. |
> | `supabase_v1_get_profile` | Get profile. |
> | `supabase_v1_get_project` | Get project. |
> | `supabase_v1_get_project_api_key` | Get project api key. |
> | `supabase_v1_get_project_api_keys` | Get project api keys. |
> | `supabase_v1_get_project_claim_token` | Get project claim token. |
> | `supabase_v1_get_project_disk_autoscale_config` | Get project disk autoscale config. |
> | `supabase_v1_get_project_function_combined_stats` | Get project function combined stats. |
> | `supabase_v1_get_project_legacy_api_keys` | Get project legacy api keys. |
> | `supabase_v1_get_project_logs` | Executes an SQL or LQL query on the project's unified logs stream. |
> | `supabase_v1_get_project_pgbouncer_config` | Get project pgbouncer config. |
> | `supabase_v1_get_project_signing_key` | Get project signing key. |
> | `supabase_v1_get_project_signing_keys` | Get project signing keys. |
> | `supabase_v1_get_project_tpa_integration` | Get project tpa integration. |
> | `supabase_v1_get_project_usage_api_count` | Get project usage api count. |
> | `supabase_v1_get_project_usage_request_count` | Get project usage request count. |
> | `supabase_v1_get_readonly_mode_status` | Get readonly mode status. |
> | `supabase_v1_get_realtime_config` | Get realtime config. |
> | `supabase_v1_get_restore_point` | Get restore point. |
> | `supabase_v1_get_security_advisors` | This is an experimental endpoint. |
> | `supabase_v1_get_services_health` | Get services health. |
> | `supabase_v1_get_ssl_enforcement_config` | This is an experimental endpoint. |
> | `supabase_v1_get_storage_config` | Get storage config. |
> | `supabase_v1_get_vanity_subdomain_config` | This is an experimental endpoint. |
> | `supabase_v1_invite_external_jit_access` | Invites the external user and sets initial roles that can be assumed and for how long |
> | `supabase_v1_list_action_runs` | Returns a paginated list of action runs of the specified project. |
> | `supabase_v1_list_all_backups` | List all backups. |
> | `supabase_v1_list_all_branches` | Returns all database branches of the specified project. |
> | `supabase_v1_list_all_buckets` | List all buckets. |
> | `supabase_v1_list_all_functions` | Returns all functions you've previously added to the specified project. |
> | `supabase_v1_list_all_network_bans` | This is an experimental endpoint. |
> | `supabase_v1_list_all_network_bans_enriched` | This is an experimental endpoint. |
> | `supabase_v1_list_all_organizations` | Returns a list of organizations that you currently belong to. |
> | `supabase_v1_list_all_projects` | Returns a list of all projects you've previously created. |
> | `supabase_v1_list_all_secrets` | Returns all secrets you've previously added to the specified project. |
> | `supabase_v1_list_all_snippets` | List all snippets. |
> | `supabase_v1_list_all_sso_provider` | List all sso provider. |
> | `supabase_v1_list_available_restore_versions` | List available restore versions. |
> | `supabase_v1_list_jit_access` | Mappings of roles a user can assume in the project database |
> | `supabase_v1_list_migration_history` | List migration history. |
> | `supabase_v1_list_organization_members` | List organization members. |
> | `supabase_v1_list_project_addons` | Returns the billing addons that are currently applied, including the active compute instance size, and lists every addon option that can be provisioned with pricing metadata. |
> | `supabase_v1_list_project_tpa_integrations` | List project tpa integrations. |
> | `supabase_v1_merge_a_branch` | Merges the specified database branch |
> | `supabase_v1_modify_database_disk` | Modify database disk. |
> | `supabase_v1_oauth_authorize_project_claim` | Initiates the OAuth authorization flow for the specified provider. |
> | `supabase_v1_patch_a_migration` | Patch a migration. |
> | `supabase_v1_patch_network_restrictions` | This is an experimental endpoint. |
> | `supabase_v1_patch_postgres_config` | Patch postgres config. |
> | `supabase_v1_pause_a_project` | Pause a project. |
> | `supabase_v1_push_a_branch` | Pushes the specified database branch |
> | `supabase_v1_read_only_query` | All entity references must be schema qualified. |
> | `supabase_v1_remove_a_read_replica` | This is an experimental endpoint. |
> | `supabase_v1_remove_project_addon` | Disables the selected addon variant, including rolling the compute instance back to its previous size. |
> | `supabase_v1_remove_project_signing_key` | Remove project signing key. |
> | `supabase_v1_reset_a_branch` | Resets the specified database branch |
> | `supabase_v1_restart_a_project` | Restart a project. |
> | `supabase_v1_restore_a_branch` | Cancels scheduled deletion and restores the branch to active state |
> | `supabase_v1_restore_a_project` | Restore a project. |
> | `supabase_v1_restore_physical_backup` | Restore physical backup. |
> | `supabase_v1_restore_pitr_backup` | Restore pitr backup. |
> | `supabase_v1_review_network_restrictions` | This is an experimental endpoint. |
> | `supabase_v1_revoke_token` | This is an experimental endpoint. |
> | `supabase_v1_rollback_migrations` | Rollback migrations. |
> | `supabase_v1_run_a_query` | This is an experimental endpoint. |
> | `supabase_v1_scrape_project_metrics` | Prometheus scrape endpoint. |
> | `supabase_v1_setup_a_read_replica` | This is an experimental endpoint. |
> | `supabase_v1_shutdown_realtime` | Shutdown realtime. |
> | `supabase_v1_undo` | Undo. |
> | `supabase_v1_update_a_branch_config` | Updates the configuration of the specified database branch |
> | `supabase_v1_update_action_run_status` | Updates the status of an ongoing action run. |
> | `supabase_v1_update_a_function` | Updates a function with the specified slug and project. |
> | `supabase_v1_update_a_project` | Update a project. |
> | `supabase_v1_update_a_sso_provider` | Update a sso provider. |
> | `supabase_v1_update_auth_service_config` | Update auth service config. |
> | `supabase_v1_update_backup_schedule` | Sets the time at which the daily backup runs. |
> | `supabase_v1_update_database_password` | Update database password. |
> | `supabase_v1_update_hostname_config` | This is an experimental endpoint. |
> | `supabase_v1_update_jit_access` | Modifies the roles that can be assumed and for how long |
> | `supabase_v1_update_jit_access_config` | This is an experimental endpoint. |
> | `supabase_v1_update_network_restrictions` | This is an experimental endpoint. |
> | `supabase_v1_update_pgsodium_config` | This is an experimental endpoint. |
> | `supabase_v1_update_pooler_config` | Update pooler config. |
> | `supabase_v1_update_postgres_config` | Update postgres config. |
> | `supabase_v1_update_postgrest_service_config` | Update postgrest service config. |
> | `supabase_v1_update_project_api_key` | Update project api key. |
> | `supabase_v1_update_project_legacy_api_keys` | Update project legacy api keys. |
> | `supabase_v1_update_project_signing_key` | Update project signing key. |
> | `supabase_v1_update_realtime_config` | Update realtime config. |
> | `supabase_v1_update_ssl_enforcement_config` | This is an experimental endpoint. |
> | `supabase_v1_update_storage_config` | Update storage config. |
> | `supabase_v1_upgrade_postgres_version` | This is an experimental endpoint. |
> | `supabase_v1_upsert_a_migration` | Upsert a migration. |
> | `supabase_v1_verify_dns_config` | This is an experimental endpoint. |

## Frequently asked questions

> [accordion] Can I limit an agent to read-only Supabase operations?
>
> Yes. Write a credential policy that allows only operations matching patterns like supabase\_v1\_get\_\* and supabase\_v1\_list\_\*, and add a DENY rule for any mutating operations. Guild's credential proxy enforces the rules before the request reaches Supabase.

> [accordion] Does the Supabase integration support webhook events?
>
> No. The catalog entry for guildai\~supabase lists no webhook events, so the integration does not receive event-driven triggers from Supabase.

> [accordion] Can different agents use different Supabase accounts?
>
> Yes. You can connect a credential dedicated to a single agent from that agent's page, or scope a credential to one workspace. Guild resolves credentials in order: grants and dedicated credentials take priority over workspace and account defaults.

> [accordion] How do I give an agent only some of the available tools?
>
> Use the pick() helper from the Guild Agent SDK to select specific tools by name from SupabaseTools before spreading them into your agent's tools object. The tools page documents pick() under selecting specific tools.

## Put a governed agent on Supabase this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Supabase.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Supabase to your first agent.

## Related

**Also runs on Guild:** [Airtable](https://docs.guild.ai/integrations/airtable.md) · [BigQuery](https://docs.guild.ai/integrations/bigquery.md) · [Hex](https://docs.guild.ai/integrations/hex.md) · [Nexla](https://docs.guild.ai/integrations/nexla.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)