Setup docs

This scaffold is designed for a Vercel-hosted Next.js control plane and a Supabase Postgres data plane with durable queues.

1) Create Supabase project

Create a new Supabase project.
Enable Auth (email/password) and optionally OAuth providers (Google/GitHub).
In SQL Editor, apply migrations in supabase/migrations in order.

For OAuth and magic-link, configure Redirect URLs in Supabase Auth to include: http://localhost:3000/auth/callback and your production URL https://<your-domain>/auth/callback. For password recovery, also allow: http://localhost:3000/auth/update-password and https://<your-domain>/auth/update-password.

Note: migrations enable pgvector, pgmq, and create queue wrappers for the Edge Function worker.

2) Configure environment

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=...

# For worker-tick Edge Function (Supabase secrets)
SUPABASE_URL=...
SUPABASE_SERVICE_ROLE_KEY=...
OPENAI_API_KEY=...

The web app uses the publishable key; the worker uses the service role key to write embeddings and run traces.

3) Deploy worker

Deploy supabase/functions/worker-tick.
Set Supabase function secrets for SUPABASE_SERVICE_ROLE_KEY and OPENAI_API_KEY.
Schedule the function (pg_cron + pg_net) or ping it via an external cron.

Suggested interval for MVP: every 1 minute.

4) Use the UI

Sign up and log in.
Create an org in Dashboard.
Inside the org: create an agent and publish v1.
Create one or more Tools (HTTP allowlist) and attach them to the agent version via Tools JSON.
Optionally enable approval gates on tools and approve pending tool actions in Approvals.
Add knowledge documents (they will be embedded by the worker).
Run the agent and inspect the run trace.

Tool calling

When an agent version has tools attached, the worker runs a simple tool-calling loop using OpenAI function tools. The only built-in tool today is http_request, which is scoped bytool_id and enforced by allowlisted URL prefixes in Postgres.

Example Tools JSON:
[
  {
    "tool_id": "<uuid-from-org-tools>"
  }
]

If a tool is marked as requires_approval, the run pauses with statusawaiting_approval until an org admin approves it.