Skip to main content

​
1. Start the local app

From the repository root, run:
Open the app at http://localhost:3000. This is the preferred startup path when you want the browser to keep working after handoff. It starts the repo app wrapper in a detached local session, checks /api/health, and avoids native module issues from the desktop environment. For an isolated agent or developer worktree, use:
Open the app URL reported by the status command. Worktree login uses normal WorkOS AuthKit, so agents should make sure ~/.config/onboarding/local.env or ONBOARDING_SHARED_ENV_FILE has the shared local values before startup. A blank .env.local template is not enough for live WorkOS, Agents SDK, or workflow demos. Supabase uses the local stack by default in dev mode. The WorkOS Sandbox app needs http://localhost:*/callback as an allowed redirect URI. For local demos where every agent worktree should already be signed in, add the localhost-only auth bypass values to the shared env file:
For foreground debugging with live logs in the current terminal, run:

​
2. Open the main space

The app starts in a space page. Use the sidebar to move between saved pages, tables, settings, and chat. Useful local URLs:
  • http://localhost:3000 opens the main space.
  • http://localhost:3000/chats/new opens the agent chat.
  • http://localhost:3000/settings opens local demo settings.
  • http://localhost:3000/auth/setup explains optional AuthKit setup.
  • http://localhost:3000/api/health checks that the web app server is listening.

​
3. Run the docs preview

From the repository root, run:
Open the docs at http://localhost:3333.

​
4. Try a simple agent chat

Open /chats/new and send a clear onboarding request: Example:
If OPENAI_API_KEY is not configured, the chat shows a local fallback response. That is expected and is enough to verify the screen works.

​
5. Add local services when needed

You do not need keys for the docs preview or basic app browsing. For live agent behavior, page Preview chat, workflow runs, and Supabase table views, configure WorkOS AuthKit and sign in first, or enable the localhost-only auth bypass for local demo worktrees. Live agent behavior and page Preview also need OPENAI_API_KEY. Supabase table views and local tool writes use local Supabase by default; run pnpm db:start and pnpm db:reset:verify before testing database state. Set ONBOARDING_SUPABASE_MODE=cloud only when you intentionally want localhost to use hosted Supabase credentials. For workflow runner testing, start the app normally and start the local Inngest dev server in a second terminal. Use sh scripts/with-dev-runtime.sh pnpm inngest:dev:worktree for an isolated worktree so the worker watches that worktree’s app URL and dev-server port; verify /api/inngest and the worker listener before treating workflow runs as ready.

​
Fresh service accounts

Developers should follow docs/setup/new-project.md and the service registry in docs/setup/service-accounts.md in the repository. New billing, email, analytics and monitoring connections are not active until configured and verified.