Orbit AI Local Development Setup and Commands

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

Install dependencies

Run npm ci to install from package-lock.json.

Set required environment variables

Create a local .env file with:

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

Start the dev server

Run npm run dev. Vite listens on port 8000 (vite.config.ts).

Open the app

Open the printed local URL. Most product screens require a signed-in account and a working Supabase client configuration.

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

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

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

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

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

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

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

.
├── 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

Install dependencies with npm install.
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.
Start the frontend with npm run dev.
For Supabase-backed features, validate the configured project with the bootstrap scripts.
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.

Platform

Audience Engine

Orbit Control

Control Center

Orbit AI Local Development Setup and Commands

Supported environments

Prerequisites

Local browser launch

Server-side secrets

npm scripts

Core

Desktop

Cloudflare

Supabase

Mobile

Repository layout

Suggested workflow

Common setup failures

Common maintainer checks

Recommended reading order

​Supported environments

​Prerequisites

​Local browser launch

​Server-side secrets

​npm scripts

​Core

​Desktop

​Cloudflare

​Supabase

​Mobile

​Repository layout

​Suggested workflow

​Common setup failures

​Common maintainer checks

​Recommended reading order

Supported environments

Prerequisites

Local browser launch

Server-side secrets

npm scripts

Core

Desktop

Cloudflare

Supabase

Mobile

Repository layout

Suggested workflow

Common setup failures

Common maintainer checks

Recommended reading order