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

1. Install dependencies

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

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

3. Start the dev server

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

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

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

1. Match tool versions

   Use the Node and npm versions supported by the project’s lockfile and scripts.

2. Install and configure

   Install from the root manifest using the established lockfile workflow. Obtain approved local configuration from maintainers without copying production credentials.

3. Run against a development backend

   Run the Vite app locally and sign in with a test account in a non-production project.

4. Make one focused change

   Test the affected screen or flow, including expected error states.

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

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

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

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.