Codex + Powabase

Example apps

Real apps, each from one prompt. Copy any of them and give it to Codex.

Where Codex keeps your keys

Codex doesn't store app secrets. It decides which of your environment variables reach the commands it runs through shell_environment_policy in ~/.codex/config.toml, so keep BASE_URL and API_KEY in your shell or in a gitignored .env your server code loads. The Service Role key stays in server code, and anything for the browser uses the Anon key. If you tighten that policy, remember that ignore_default_excludes = false drops every variable whose name contains KEY, SECRET, or TOKEN, API_KEY included.

Codex example

# What Codex writes for a Python backend: run a Powabase agent server-side.
import os
import requests

BASE_URL = os.environ["BASE_URL"]
API_KEY = os.environ["API_KEY"]  # Service Role (Secret) Key
HEADERS = {"apikey": API_KEY, "Authorization": f"Bearer {API_KEY}"}


def ask_agent(agent_id: str, message: str, session_id: str | None = None) -> dict:
    body = {"message": message}
    if session_id:
        body["session_id"] = session_id  # continue a multi-turn conversation
    res = requests.post(
        f"{BASE_URL}/api/agents/{agent_id}/run", headers=HEADERS, json=body, timeout=60
    )
    res.raise_for_status()
    return res.json()

POST /api/agents/{id}/run returns the whole reply as JSON in one call, with no tool use. When the agent needs its tools, Codex should call /run/stream and read the server-sent events instead.

Connecting to Powabase from any tool

Mechanics that don’t change from tool to tool.

• Every call to /api/* or /rest/v1/* needs two headers, apikey and Authorization: Bearer, both set to the same key. Sending only one is the most common cause of a 401.

  Docs↗

• The Database URL from the Connect modal is PgBouncer in transaction mode, not a direct Postgres connection. Disable prepared statements in your driver, or you'll hit prepared statement "..." does not exist. No LISTEN/NOTIFY and no session-level SET across statements. Use Realtime for change notifications; SET LOCAL inside a transaction otherwise. The username and database in the URL are both your project ref, not postgres.

  Docs↗

• @supabase/supabase-js mostly works for the BaaS surface (PostgREST, Auth, Storage, Realtime) when you point it at your project URL with the Anon key. It doesn't cover the /api/* AI surface (agents, knowledge bases, orchestrations), which you call over plain REST. There's no /graphql/v1 route: point any GraphQL client at POST /rest/v1/rpc/graphql instead.

  Docs↗

Common errors

Calls to your project URL fail while Codex runs the code

Cause: Codex's default workspace-write sandbox runs with network access turned off, so commands it runs can't reach *.p.powabase.ai until you allow it.

Fix: Approve the network request when Codex asks, or opt in for the workspace with network_access = true under [sandbox_workspace_write] in config.toml.

KeyError: 'API_KEY' when Codex runs your script, even though it's set in your shell

Cause: shell_environment_policy filtered it out. With ignore_default_excludes = false, Codex removes names containing KEY, SECRET, or TOKEN; inherit = "none" starts from an empty environment.

Fix: Keep ignore_default_excludes at its default (true), keep the default inherit setting, and exclude only the variables you actually want hidden.

401 Unauthorized

Cause: Only one of the apikey / Authorization headers was sent.

Fix: Send both, set to the same key. Docs↗

prepared statement "..." does not exist

Cause: PgBouncer's transaction-mode pooler moved you to a different server connection.

Fix: Disable prepared statements in your driver's config. Docs↗

A query that should return rows comes back empty, or a write is silently rejected

Cause: Row Level Security on your own tables. New public tables ship with RLS off, but once you add policies they gate every request.

Fix: Check the policy's USING/WITH CHECK clause and confirm which role (anon, authenticated, service_role) you actually authenticated as. Docs↗

The Service Role key turns up in a browser bundle or other client-visible code

Cause: It was used somewhere that ships to the client instead of staying server-side.

Fix: Move the call server-side; use the Anon key with RLS for anything client-visible. If it shipped, rotate it in Studio. Docs↗

FAQ