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

# Orbit AI Local Development Setup and Commands

> Set up the Orbit AI development environment: prerequisites, local browser launch, required secrets, build commands, and common setup failures.

This page explains how to run the Orbit AI app locally, what you need installed, which environment variables are required, and how to handle the most common setup failures.

## Supported environments

* **Browser:** Vite serves the single-page app locally. Production hosting must serve `dist/` and route unknown paths to the SPA entry.
* **Desktop:** Electron package targets Windows portable/NSIS and Linux AppImage/deb/dir via `electron-builder`.
* **Mobile:** Capacitor 8 targets Android and iOS. Native project builds require Android Studio/SDK or Xcode. Feature parity is not established; see `docs/mobile/PLATFORM_LIMITATIONS.md`.

## Prerequisites

You need Node.js and npm compatible with the lockfile, Git, and a configured Supabase project. Desktop and mobile release builds require Electron Builder and platform-specific dependencies; mobile builds additionally need Android Studio or Xcode. Versions and support policy are not declared in the repository.

## Local browser launch

<Steps>
  <Step title="Install dependencies">
    Run `npm ci` to install from `package-lock.json`.
  </Step>

  <Step title="Set required environment variables">
    Create a local `.env` file with:

    ```text theme={"dark"}
    VITE_SUPABASE_URL=https://your-project.supabase.co
    VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
    ```

    Only these two Vite variables are mandatory at client initialization (`src/integrations/supabase/client.ts`).
  </Step>

  <Step title="Start the dev server">
    Run `npm run dev`. Vite listens on port 8000 (`vite.config.ts`).
  </Step>

  <Step title="Open the app">
    Open the printed local URL. Most product screens require a signed-in account and a working Supabase client configuration.
  </Step>
</Steps>

<Warning>
  The publishable/anonymous client key is browser-visible. Never put service-role or provider secrets in `VITE_*` variables.
</Warning>

## Server-side secrets

Edge Function secrets are server-side and vary by feature. Secret names discovered in source include:

* `SUPABASE_URL`
* `SUPABASE_ANON_KEY`
* A service-role or secret key where privileged operations require it
* `OPENAI_API_KEY` / `AI_API_KEY`
* `GEMINI_API_KEY`
* `STRIPE_SECRET_KEY`
* `STRIPE_WEBHOOK_SECRET`
* Origin and app settings

Consult each function and deployment setup before configuring. Secret values are intentionally omitted. `.env` exists in this checkout; do not copy or publish its contents.

## npm scripts

All commands are declared in `package.json`.

### Core

```bash theme={"dark"}
npm run dev          # Vite development server on port 8000
npm run build        # Production Vite build
npm run preview      # Serve built app locally
npm run lint         # ESLint over src, chat, extension, scripts
npm test             # Vitest run
```

### Desktop

```bash theme={"dark"}
npm run desktop:dev       # Run Vite and Electron together
npm run desktop:build     # Desktop build
npm run desktop:release   # Desktop release (invokes PowerShell scripts)
npm run desktop:setup     # Windows installer build
npm run desktop:portable  # Windows portable build
```

### Cloudflare

```bash theme={"dark"}
npm run cloudflare:dev     # Cloudflare dev server
npm run cloudflare:deploy  # Build and deploy to Cloudflare Worker
npm run cloudflare:check   # Wrangler dry run after build
```

### Supabase

```bash theme={"dark"}
npm run supabase:check   # Supabase bootstrap validation script
npm run supabase:deploy  # Supabase bootstrap deployment script
npm run sql:generate     # Generate SQL from project source script
```

### Mobile

```bash theme={"dark"}
npm run mobile:build   # Build then cap sync
npm run mobile:sync    # Capacitor sync
npm run mobile:android # Build, sync Capacitor, and open Android project
npm run mobile:ios     # Build, sync Capacitor, and open iOS project
```

## Repository layout

```text theme={"dark"}
.
├── src/                        # Main React application source
├── app/                        # App-specific screens or app shell sources
├── chat/                       # Chat-related app modules
├── components/                 # Shared UI, layout, dialogs, loaders, etc.
├── pages/                      # App screens and route-level pages
├── lib/                        # Auth, workspace, analytics, billing, theme and domain logic
├── hooks/                      # Reusable hooks
├── supabase/                   # Supabase config, migrations, edge functions
├── electron/                   # Electron main/preload code
├── public/                     # Static public assets
├── docs/                       # Product and architecture documentation set
├── scripts/                    # Build and bootstrap automation
├── build/                      # Desktop build scripts/icons/packaging
├── discord-bot/                # Discord bot companion package
├── launcher/                   # Launcher app sources
├── extension/                  # Browser extension tooling
├── ios/                        # Capacitor iOS project
├── android/                    # Capacitor Android project
├── examples/                   # Example/reference modules
├── tmp/                        # Reference and experimental content
├── package.json                # Root app/build configuration
├── vite.config.ts              # Vite app configuration
├── wrangler.jsonc              # Cloudflare deployment config
├── README.md                   # Top-level project readme
├── docs/README.md              # Documentation index
└── FULL_APP_DOCUMENTATION.md   # Single-source app overview
```

## Suggested workflow

1. Install dependencies with `npm install`.
2. Configure the local app using the project's approved private setup instructions. Do not copy production credentials into source files, documentation, chat, or a public repository.
3. Start the frontend with `npm run dev`.
4. For Supabase-backed features, validate the configured project with the bootstrap scripts.
5. For desktop or mobile builds, use the corresponding `desktop:*` or `mobile:*` scripts.

## Common setup failures

* **Missing Supabase public config:** the client throws during app startup. Set both required `VITE_` variables and restart Vite.
* **Blank or error startup:** confirm dependencies and the Supabase URL/key pair, then inspect the browser console. The app has a startup error boundary and a configuration fallback.
* **Auth, tables, or functions fail:** confirm the target Supabase project has the required migrations, Auth settings, Edge Functions, and secrets deployed. `npm run supabase:check` checks deployment prerequisites; it does not prove runtime feature health.
* **OAuth or email redirect errors:** confirm Supabase Auth URL allow-lists and function CORS origins against the exact development or production host.

## Common maintainer checks

* Verify private local configuration and backend connectivity without printing credentials.
* Ensure auth and role permissions are correctly configured.
* Verify Stripe and payment webhook configuration for billing flows.
* Ensure `dist/` builds cleanly before deployment.
* Check migration and edge function alignment before a production rollout.

## Repository orientation

* Start with `src/main.tsx` and `src/App.tsx` for initialization, providers, routing, and access guards.
* Read `src/components/AppLayout.tsx` for global navigation and shell behavior.
* Read `src/pages/` for routed screens, `src/components/` for shared UI, and `src/lib/` for domain and service logic.
* Use `src/integrations/supabase/client.ts` and `types.ts` to understand client configuration and generated schema types.
* Read migrations before changing database behavior. Treat them as source-controlled history, not proof of deployed state.
* Read the individual Edge Function and its `_shared/` helper for provider calls and server-side validation.
* Review Electron `main` and `preload` code before adding native bridge methods.

## Development sequence

<Steps>
  <Step title="Match tool versions">
    Use the Node and npm versions supported by the project's lockfile and scripts.
  </Step>

  <Step title="Install and configure">
    Install from the root manifest using the established lockfile workflow. Obtain approved local configuration from maintainers without copying production credentials.
  </Step>

  <Step title="Run against a development backend">
    Run the Vite app locally and sign in with a test account in a non-production project.
  </Step>

  <Step title="Make one focused change">
    Test the affected screen or flow, including expected error states.
  </Step>

  <Step title="Verify before proposing">
    Run the relevant lint, test, and build commands. For database or function work, verify the migration or function in an isolated project before deployment.
  </Step>
</Steps>

<Note>
  Some platform-specific scripts expect Windows, Android, iOS, or deployment tooling. A script being defined does not mean its prerequisites exist on every machine.
</Note>

## Browser, desktop, and mobile validation

At minimum, validate the changed user journey in a browser. If a change touches Electron bridge methods, test the packaged desktop runtime and confirm only intended methods are exposed. If it touches Capacitor, validate permission and lifecycle behavior on the relevant device or emulator. Do not assume browser APIs behave identically in native WebViews.

For user-visible workflows, check:

* Signed-out access and redirect behavior
* Loading, empty, success, and failure states
* Unauthorized account behavior
* Keyboard focus and narrow viewport layout
* Persistence after refresh, where the feature promises it
* No duplicate writes when retrying
* A safe and comprehensible error message

## Build, test, and release cautions

Run focused tests first, then the full lint, test, and build commands when appropriate. Review generated bundles and packaged app contents for accidental credential inclusion. Check version and release metadata and platform artifacts before publishing. Do not deploy migrations, functions, Worker assets, or desktop builds to production without an approved release process and a verified target.

## Documentation maintenance

The user guides are based on source and repository documentation, not a live audit of every hosted feature. When product behavior changes:

1. Update the user instructions and the capability guide together.
2. Confirm route names against the active route table.
3. Confirm labels against the current screen, not a legacy screenshot or unused component.
4. Describe externally configured behavior as conditional until verified in a test deployment.
5. Keep instructions free of credentials, private URLs, account identifiers, and personal data.
6. Record unsupported, redirected, or unverified features explicitly rather than presenting them as ready.

## Recommended reading order

For a newcomer, the best first pass is:

1. `README.md`
2. `docs/README.md`
3. `docs/orbit-ai/overview.md`
4. `docs/orbit-ai/architecture.md`
5. `docs/orbit-ai/getting-started.md`
6. `src/App.tsx` for route and guard behavior
7. `supabase/` for backend logic and database state

<Note>
  Open verification items: live screenshot capture for sign-in, chat, history, settings, and privacy screens needs a test tenant with synthetic data. Test tenant requirements for standard, workspace-member, staff, and admin roles, plus MFA states and entitlements, are not yet confirmed.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.