> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubbla.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the app and docs locally.

## 1. Start the local app

From the repository root, run:

```sh theme={null}
pnpm app:start
pnpm app:status
```

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:

```sh theme={null}
sh scripts/with-dev-runtime.sh node scripts/local-env.mjs presence WORKOS_API_KEY WORKOS_CLIENT_ID WORKOS_COOKIE_PASSWORD OPENAI_API_KEY NEXT_PUBLIC_SUPABASE_URL SUPABASE_SERVICE_ROLE_KEY
sh scripts/with-dev-runtime.sh pnpm app:worktree:start
sh scripts/with-dev-runtime.sh pnpm app:worktree:status
```

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:

```sh theme={null}
ONBOARDING_LOCAL_AUTH_BYPASS=1
ONBOARDING_LOCAL_AUTH_USER_EMAIL=ashley@example.com
ONBOARDING_LOCAL_AUTH_USER_ID=local-ashley
ONBOARDING_LOCAL_AUTH_USER_NAME=Ashley Bettridge
```

For foreground debugging with live logs in the current terminal, run:

```sh theme={null}
sh scripts/start-app.sh
```

## 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:

```sh theme={null}
pnpm docs:dev
```

Open the docs at `http://localhost:3333`.

## 4. Try a simple agent chat

Open `/chats/new` and send a clear onboarding request:

Example:

```text theme={null}
Onboard Maya Chen as a service contractor in Mining, starts July 15.
Leader is Jordan Pike.
```

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.