Kuunda Cloud Managed

Kuunda Cloud Managed = Kuunda BaaS (REST API, Auth, Storage, Realtime) + Management API for vibe-coding tools (Lovable, Bolt, CI, scripts).

Two planes

Authentication

Create a Personal Access Token (kuunda_pat_*) in the console: Account → Access Tokens. Permissions:

• database_query (opt-in, off by default): POST /v1/projects/{ref}/database/query — SQL outside REST API/RLS, logged, 30 req/min. Without this permission: 403 pat_database_query_forbidden.
• projects_create (opt-in): POST /v1/projects (new project in the same organisation)
• edge_functions (opt-in): deploy / list / delete Edge Functions via POST /v1/projects/{ref}/functions/deploy (Edge Functions console, or the repo CLI packages/cli — the npm package @kuunda/cli is not published). Without this permission: 403 pat_edge_functions_forbidden.

For Lovable / CI: in the console, Prepare for CI / Lovable, or Enable SQL on an existing PAT (a secret already in CI stays valid). Recreate a token only if the secret was lost.

Authorization: Bearer kuunda_pat_xxxxx

Project discovery

GET https://api.kuunda-cloud.com/v1/projects/{ref}
→ ref, schema, rest_url, auth_url, anon_key, sdk…

Create a project (Managed)

POST https://api.kuunda-cloud.com/v1/projects
{ "name": "Mon app Lovable" }
→ project { ref, anon_key, rest_url, schema, … }

Run SQL (migrations)

Requires a PAT with database_query: true. SQL is validated (AST + lexer outside strings, fail-closed if unreadable) and runs as {schema}_owner, not superuser. Audit log + 30 req/min limit (Redis, shared across instances).

POST https://api.kuunda-cloud.com/v1/projects/{ref}/database/query
{ "query": "CREATE TABLE …; NOTIFY pgrst, 'reload schema';" }

Deploy an Edge Function (agents / CI)

Requires a PAT with edge_functions: true. Equivalent of supabase functions deploy. Local files: kuunda/functions/<name>/index.ts and optionally kuunda/functions/_shared/ (bundled automatically). The runtime injects KUUNDA_URL, KUUNDA_ANON_KEY, KUUNDA_SERVICE_ROLE_KEY, KUUNDA_DB_SCHEMA, KUUNDA_PROJECT_REF (SUPABASE_* aliases too).

# Management API (PAT edge_functions)
POST https://api.kuunda-cloud.com/v1/projects/{ref}/functions/deploy
{ "name": "hello", "source": "Deno.serve(() => new Response('ok'))", "files": { "_shared/cors.ts": "…" } }

# CLI depuis le monorepo (packages/cli) — @kuunda/cli n’est pas sur npm
# npx kuunda functions deploy hello

# Secrets métier (upsert)
PUT https://api.kuunda-cloud.com/v1/projects/{ref}/functions/secrets
{ "functionName": "hello", "key": "GENIUS_API_KEY", "value": "…" }

In Cursor, the repo MCP server (packages/mcp-server) also exposes deploy_edge_function (kuunda_mcp_* token generated in Settings → API → MCP).

Functions runtime contract (all projects)

Handler: export default async (req: Request) => Response or Deno.serve(handler). HTTPS Deno imports (esm.sh, jsr, deno.land) allowed. Compile / import / timeout failure: HTTP 500 JSON { "error", "message", "request_id" } with CORS. An infra 502 gateway also has CORS + request_id. OPTIONS preflight echoes Access-Control-Request-Headers (SDK: content-profile, x-project-ref, custom headers).

Realtime WebSocket

For an active project, shared Realtime is reachable without a manual toggle: wss://{ref}.kuunda-cloud.com/realtime/v1/websocket?apikey=…&vsn=1.0.0 (SDK kuunda.channel(…)). Dedicated-database projects get a sidecar on first subscribe. Tables: supabase_realtime publication (Realtime console or import).

Client in generated code

npm install @kuunda/kuunda-js

import { createClient } from '@kuunda/kuunda-js';

const kuunda = createClient(
  process.env.NEXT_PUBLIC_KUUNDA_URL!,
  process.env.NEXT_PUBLIC_KUUNDA_ANON_KEY!,
  { dbSchema: process.env.KUUNDA_DB_SCHEMA! }
);

KUUNDA_DB_SCHEMA = proj_ + project UUID (32 hex, no dashes), not the short 8-character ref.

SDK and key mapping

Use @kuunda/kuunda-js with the Management API https://api.kuunda-cloud.com/v1, and kuunda_anon_* / kuunda_pat_* keys.