CodeXDocumentation

Connect Supabase to CodeX

Complete guide to integrating your Supabase project with the CodeX desktop app. Get up and running in 5 minutes with our quick start guide.

Prerequisites

Make sure you have these ready before starting

Supabase account

Supabase project (Organization → New project)

Region: nearest to your users

Database password: store securely

🚀 Quick Start (5 minutes)

Get connected fast with these essential steps

1Create a project in Supabase.

Go to Project Settings → API, copy:

• Project URL (REST URL)
• anon public key
• service_role key (store securely; NEVER ship to the client)

Go to Authentication → URL Configuration → Add redirect URL(s):

codex://supabase-oauth-return

(Optional dev) codex://supabase-oauth-return?env=dev

In CodeX, open Settings → Integrations/Providers → Supabase and paste:

• SUPABASE_URL = <Project URL>
• SUPABASE_ANON_KEY = <anon key>
• (Optional) SUPABASE_SERVICE_ROLE_KEY for server-side jobs

5Click "Test Connection" → expect "Connected".

🔗 Deep Link Specification

Technical details for the CodeX Electron app integration

Protocol Details

• Protocol: codex
• Hostname: supabase-oauth-return
• Required params: token, refreshToken, expiresIn

Example URL

codex://supabase-oauth-return?token=eyJhbGciOi...&refreshToken=eyJhbGciOi...&expiresIn=3600

🔧 Environment Variables Mapping

Variable	Where to find in Supabase	Notes
SUPABASE_URL	Project Settings → API → Project URL	REST base URL
SUPABASE_ANON_KEY	Project Settings → API → anon public key	Safe for client use with RLS
SUPABASE_SERVICE_ROLE_KEY	Project Settings → API → service_role	Server-side only, never in CodeX

🗄️ Database Setup Example

Sample SQL to get you started with CodeX tables

create table if not exists codex_apps (
  id uuid primary key default gen_random_uuid(),
  name text not null,
  created_at timestamp with time zone default now()
);

alter table codex_apps enable row level security;
create policy "Authenticated can read" on codex_apps
  for select
  using (auth.uid() is not null);

🧪 Testing the Connection

From CodeX:

Click "Test Connection" in the Supabase integration settings.

From terminal (sanity check):

curl -H "Authorization: Bearer <anon_key>" \

"<SUPABASE_URL>/rest/v1/codex_apps?select=*"

Expect 200 OK and an array (possibly empty).

🔧 Troubleshooting

Invalid redirect: Ensure codex://supabase-oauth-return is added in Auth → URL Configuration.

401 Unauthorized: Verify anon key and REST URL are correct.

macOS deep link not opening CodeX: Move app to Applications, then reopen.

Windows protocol not registered: Relaunch CodeX (or reinstall if needed).

Security: Never ship service_role to clients. Use on a server/Cloud Functions instead.

❓ Frequently Asked Questions

Do I need a backend?

Not for basic read flows with RLS; anon key is sufficient. Use server-side functions for privileged operations.

Multiple environments?

Use separate Supabase projects/keys and keep per‑env profiles in CodeX.

Key rotation?

You can rotate anon/service_role in Supabase and update CodeX settings.

Ready-to-Copy .env

.env

SUPABASE_URL=https://your-project.supabase.co

SUPABASE_ANON_KEY=eyJhbGciOi...

# server-side only

SUPABASE_SERVICE_ROLE_KEY=...

Quick Actions

On This Page