| Service | How to run | Port |
|---|---|---|
| Supabase stack (Postgres, Auth, PostgREST, Storage, pgmq) | sudo supabase start from repo root (Docker; start the daemon first with sudo service docker start if needed) |
54321 (API), 54322 (DB), 54323 (Studio) |
Next.js app (apps/cursor) |
bun dev from apps/cursor (see README and apps/cursor/package.json for standard commands: lint, typecheck, seed:*) |
3000 |
Next.js app (apps/grok-bot, Grok Bot Directory) |
bun dev from apps/grok-bot (see apps/grok-bot/README.md; bun run seed:marketplace seeds from the x.ai/bot marketplace; GROK_BOT_DEV_LOGIN=1 adds a local password sign-in) |
3001 |
Lint from repo root: bunx biome ci . (matches CI in .github/workflows/ci.yml). There is no automated test suite.
bunis installed via npm into~/.local/bin(onPATHvia~/.bashrc); the standalone bun.sh installer is blocked by the network egress policy.- The repo's dated migrations assume a pre-existing hosted base schema.
supabase/migrations/00000000000000_local_base_schema.sqlreconstructs it (tables, signup trigger, slug triggers,pgmq_publicwrappers, storage policies) so a freshsupabase start/supabase db resetworks locally. It is guarded to be a no-op where objects already exist. - App env lives in
apps/cursor/.env(gitignored). For local dev it uses the Supabase CLI's well-known local default keys (supabase statusprints them) withNEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321.CRON_SECRETguards/api/queue/plugin-scans/drainand/api/cron/*. - The login page only offers GitHub/Google OAuth, which are not configured locally. Create a confirmed user via the GoTrue admin API (
POST {SUPABASE_URL}/auth/v1/admin/userswith the secret key,"email_confirm": true); a DB trigger provisions thepublic.usersprofile row. To get a browser session, add a temporary route that callssupabase.auth.signInWithPassword(...)with the server client (do not commit it). To use/admin/pluginsand the MCP server, add the user to thepublic.adminstable:insert into public.admins (user_id) values ('<id>'). Email rows only match Google/GitHub identities, so local password users need auser_idrow. - Cache Components (
cacheComponents: true) makes pages withgenerateStaticParamsthrow 500 on an empty database — seed at least one active plugin. Usebun run seed:extract/seed:insert, but note: the insert script must be run asbun run --conditions=react-server --env-file=apps/cursor/.env apps/cursor/src/scripts/insert-from-jsonl.tsor theserver-onlyimport throws under plainbun run. GitHub Code Search (used byseed:extractdiscovery) is heavily rate-limited; hand-writingapps/cursor/.seed/candidates.jsonwith{"candidates":[{"owner":...,"repo":...,"source":"seed:topic","matchedQuery":"manual"}]}skips discovery. - The quickest seed is the Cursor Marketplace import:
bun run seed:marketplace-pluginsfromapps/cursorinserts ~500 official plugins from the publicListMarketplacePluginscatalog in about 20 seconds (no GitHub rate limits) and is safe to re-run. - Plugin logos can come from any host (submitted URLs, site icons, GitHub avatars). Only hosts in
apps/cursor/src/lib/image-hosts.mjs(cursor.directory'simages.remotePatterns) and grok-bot'sOPTIMIZED_HOSTSare optimized bynext/image; logos from other hosts are rendered unoptimized rather than throwing. - After changing
.envor database content backing cached pages, restartbun dev(andrm -rf apps/cursor/.nextif stale renders persist) — hot reload does not invalidate Cache Components output. - Without
XAI_API_KEY, plugin submission works but the security scan errors (plugin lands in the admin "Scan issues" queue, where an admin can publish it manually). This is expected locally. - Supabase
edge_runtimeis disabled insupabase/config.toml(no edge functions in this app; its boot probe needs deno.land which is blocked). - Community Plugins MCP server (
/api/mcp): the local Supabase OAuth 2.1 server is enabled inconfig.toml. Register the client withbun run mcp:create-oauth-clientfromapps/cursor(add--redirect-uri http://localhost:<port>/callbackfor a local test client), put the printed ID inMCP_OAUTH_CLIENT_IDSin.env, and restartbun dev. Locally the authorization server metadata is served athttp://127.0.0.1:54321/auth/v1/.well-known/oauth-authorization-server(the RFC 8414 path-inserted URL 404s), which MCP SDK clients find via their OIDC fallback. Drive the flow with the official MCP client SDK (@modelcontextprotocol/sdk): a 401 from/api/mcpstarts discovery, the browser step lands on/oauth/consent. GoTrue auto-approves clients a user already consented to on the first authorization-details fetch (the code is issued immediately and the authorization is consumed);delete from auth.oauth_consentsresets that locally. - If
supabase startfails with Realtime "connection not available" while initialising the schema, containers cannot reach each other because a legacy iptablesFORWARD DROPpolicy is present:sudo iptables-legacy -P FORWARD ACCEPT, then retry. Without systemd, start Docker withsudo dockerdin a tmux session.