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

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