Installation

Overview

Polaris IDE can be run in two ways:

Cloud version: Use Polaris directly in your browser at polaris.dev
Self-hosted: Clone and run locally for development or customization

This guide covers self-hosted installation.

Prerequisites

Before you begin, ensure you have:

Node.js

Version 20.09 or higher

Package manager

npm, pnpm, or yarn

Git

For cloning the repository

API accounts

Stack Auth, Convex, AI providers

Check your Node.js version:

node --version
# Should output v20.09.0 or higher

Required accounts

You’ll need to create accounts with these services:

Service	Purpose	Required	Free Tier
Stack Auth	Authentication & user management	Yes	Yes
Convex	Real-time database	Yes	Yes
Trigger.dev	Background jobs	Yes	Yes
OpenRouter	AI model routing (Kimi K2.5)	One of AI providers	No
Cerebras	Fast AI inference (GLM-4.7)	One of AI providers	Yes
Autumn	Subscription billing	Optional	Yes
Sentry	Error tracking	Optional	Yes
Firecrawl	Web scraping for AI	Optional	Yes

You must configure at least one AI provider (OpenRouter or Cerebras). OpenRouter with Kimi K2.5 is recommended for best results.

Installation methods

Web version
Desktop (Electron)

Install for web development

Clone the repository

git clone https://github.com/code-with-antonio/polaris.git
cd polaris

Install dependencies

npm install

Installation takes 2-5 minutes depending on your internet connection.

Set up environment variables

Create a .env.local file in the root directory:

cp .env.example .env.local

Edit .env.local with your API keys:

.env.local

# Stack Auth (required)
NEXT_PUBLIC_STACK_PUBLISHABLE_KEY=your_stack_publishable_key
STACK_SECRET_KEY=your_stack_secret_key

# Convex (required)
NEXT_PUBLIC_CONVEX_URL=your_convex_url
CONVEX_DEPLOYMENT=your_deployment_name
POLARIS_CONVEX_INTERNAL_KEY=random_string_you_generate

# AI Provider - Choose at least one
OPENROUTER_API_KEY=your_openrouter_key  # Moonshot AI Kimi K2.5 (preferred)
CEREBRAS_API_KEY=your_cerebras_key  # Cerebras GLM-4.7 (free fallback)

# Autumn (optional - for billing)
AUTUMN_SECRET_KEY=your_autumn_secret
AUTUMN_API_URL=https://api.autumn.dev
NEXT_PUBLIC_AUTUMN_PRO_MONTHLY_PRODUCT_ID=your_monthly_product_id
NEXT_PUBLIC_AUTUMN_PRO_YEARLY_PRODUCT_ID=your_yearly_product_id

# Sentry (optional - for error tracking)
SENTRY_DSN=your_sentry_dsn

# Firecrawl (optional - for web scraping)
FIRECRAWL_API_KEY=your_firecrawl_key

Generate a random string for POLARIS_CONVEX_INTERNAL_KEY:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

This key secures internal API calls between Inngest and Convex.

Start Convex development server

In one terminal window:

npx convex dev

Expected output:

✔ Convex functions ready! (convex/)
└─ https://your-deployment.convex.cloud

Convex dev server watches for changes to convex/ directory and hot-reloads functions automatically.

Start Trigger.dev development server

In a second terminal window:

npx trigger.dev@latest dev

Expected output:

✔ Trigger.dev dev server running
└─ http://localhost:3030

Trigger.dev handles background jobs like AI message processing and file operations.

Start Next.js development server

In a third terminal window:

npm run dev

Expected output:

▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Network:      http://192.168.1.100:3000

✓ Ready in 2.5s

Open Polaris in your browser

Visit http://localhost:3000You should see the Polaris landing page. Click “Sign Up” to create your first account.

Install Electron desktop app

Clone and install dependencies

git clone https://github.com/code-with-antonio/polaris.git
cd polaris
npm install

Set up environment variables

Same as web version - create .env.local with all required keys:

cp .env.example .env.local
# Edit .env.local with your API keys

Start Convex and Trigger.dev

In separate terminals:

Terminal 1 - Convex

npx convex dev

Terminal 2 - Trigger.dev

npx trigger.dev@latest dev

Run Electron in development mode

npm run electron:dev

This command:

Builds the Next.js app for Electron
Compiles Electron main process TypeScript
Launches the Electron app

The Electron app runs Next.js locally and opens in a native window. Changes to frontend code hot-reload automatically.

Build for production

Create distributable packages:

npm run electron:build
# Outputs to dist/
# Creates .dmg installer

Building for production requires:

4GB+ RAM
2GB+ free disk space
All environment variables configured

Configuration details

Stack Auth setup

Create a project at stack-auth.com
Enable GitHub OAuth provider:
- Go to Settings → OAuth Providers
- Enable GitHub
- Add callback URL: http://localhost:3000/handler/oauth/callback
Copy your API keys to .env.local

NEXT_PUBLIC_STACK_PUBLISHABLE_KEY=pk_live_...
STACK_SECRET_KEY=sk_live_...

Convex setup

Create a project at convex.dev
Run npx convex dev to link your local project
Convex will auto-generate .env.local entries:

NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_DEPLOYMENT=prod:your-deployment

Generate internal key for Inngest:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Add output to POLARIS_CONVEX_INTERNAL_KEY

AI provider setup

Option 1: OpenRouter (Moonshot AI Kimi K2.5) - Recommended

Sign up at openrouter.ai
Create an API key in Keys section
Add to .env.local:

OPENROUTER_API_KEY=sk-or-...

Option 2: Cerebras (GLM-4.7) - Free tier available

Get API key at inference.cerebras.ai
Add to .env.local:

CEREBRAS_API_KEY=csk-...

Polaris will use OpenRouter (Kimi K2.5) as the primary model. Cerebras (GLM-4.7) is used as a fallback if OpenRouter is unavailable.

Autumn billing setup (Optional)

Create account at autumn.dev
Create two products:
- Pro Monthly ($29/mo)
- Pro Yearly ($290/yr)
Add product IDs to .env.local:

AUTUMN_SECRET_KEY=sk_...
NEXT_PUBLIC_AUTUMN_PRO_MONTHLY_PRODUCT_ID=prod_...
NEXT_PUBLIC_AUTUMN_PRO_YEARLY_PRODUCT_ID=prod_...

Database schema

Polaris uses Convex with the following tables:

convex/schema.ts

users: {
  stackUserId: string,        // Stack Auth user ID
  email: string,
  subscriptionStatus: "free" | "active" | "trialing" | "paused",
  subscriptionTier: "free" | "pro_monthly" | "pro_yearly",
  projectLimit: number,       // 10 for free, unlimited for pro
}

projects: {
  name: string,
  ownerId: string,            // Stack Auth user ID
  importStatus: "importing" | "completed" | "failed",
  exportStatus: "exporting" | "completed" | "failed",
}

files: {
  projectId: Id<"projects">,
  parentId: Id<"files"> | null,
  name: string,
  type: "file" | "folder",
  content: string | null,     // Text files only
  storageId: Id<"_storage"> | null, // Binary files
}

conversations: {
  projectId: Id<"projects">,
  title: string,
}

messages: {
  conversationId: Id<"conversations">,
  role: "user" | "assistant",
  content: string,
  status: "processing" | "completed" | "cancelled" | "failed",
}

Convex automatically creates indexes defined in schema.ts. No manual database setup required.

Scripts reference

All available npm scripts:

package.json

{
  "scripts": {
    // Development
    "dev": "next dev",
    "dev:trigger": "npx trigger.dev@latest dev",
    "electron:dev": "concurrently \"npm run electron:dev:next\" \"npm run electron:dev:electron\"",

    // Build
    "build": "next build",
    "electron:build": "npm run electron:build:next && npm run electron:build:app",
    "electron:build:win": "npm run electron:build:next && npm run electron:compile && electron-builder --win",
    "electron:build:linux": "npm run electron:build:next && npm run electron:compile && electron-builder --linux",

    // Test
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage",
    "test:e2e": "playwright test",

    // Lint
    "lint": "eslint"
  }
}

Troubleshooting

Convex connection errors

Error: ConvexError: Failed to connect to ConvexSolutions:

Check that npx convex dev is running
Verify NEXT_PUBLIC_CONVEX_URL in .env.local
Run npx convex dev --clear to reset local state
Check firewall settings (Convex uses WebSockets)

# Debug Convex connection:
npx convex dev --verbose

Stack Auth 401 errors

Error: Unauthorized: Invalid Stack Auth tokenSolutions:

Verify both publishable and secret keys in .env.local
Check Stack Auth dashboard for project status
Ensure callback URLs match your environment:
- Development: http://localhost:3000/handler/oauth/callback
- Production: https://yourdomain.com/handler/oauth/callback
Clear browser cookies and re-authenticate

# Test Stack Auth connection:
curl -H "Authorization: Bearer $STACK_SECRET_KEY" \
  https://api.stack-auth.com/v1/projects

AI suggestions not working

Error: Failed to fetch AI suggestionSolutions:

Verify at least one AI provider key is set:
- ANTHROPIC_API_KEY OR
- GOOGLE_GENERATIVE_AI_API_KEY
Check API key validity in provider dashboard
Verify network connectivity to API endpoints
Check browser console for detailed error messages

# Test OpenRouter API:
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/models

# Test Cerebras API:
curl -H "Authorization: Bearer $CEREBRAS_API_KEY" \
  https://api.cerebras.ai/v1/models

Electron app won't start

Error: Electron failed to startSolutions:

Ensure Next.js dev server is running first:

npm run dev
# Wait for "Ready in X.Xs"
# Then in another terminal:
npm run electron:dev

Delete dist-electron/ and rebuild:

rm -rf dist-electron
npm run electron:compile

Check electron/main/index.ts for errors
Verify port 3000 is available (not used by another app)

Port already in use

Error: Port 3000 is already in useSolutions:

Kill the process using port 3000:

macOS/Linux

lsof -ti:3000 | xargs kill -9

Windows

netstat -ano | findstr :3000
taskkill /PID <PID> /F

Or use a different port:
```
PORT=3001 npm run dev
```

Module not found errors

Error: Cannot find module '@/components/ui/button'Solutions:

Delete node_modules/ and reinstall:

rm -rf node_modules package-lock.json
npm install

Check TypeScript paths in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Restart your IDE/editor to reload TypeScript server

Next steps

Quick start guide

Create your first project with AI

Editor features

Learn keyboard shortcuts and advanced editing

Deploy to production

Host Polaris on Vercel or your own server

Contributing

Contribute to Polaris development

Getting Started

Core Features

AI Features

Desktop App

Integrations

Overview

Prerequisites

Node.js

Package manager

Git

API accounts

Required accounts

Installation methods

Install for web development

Install Electron desktop app

Configuration details

Stack Auth setup

Convex setup

AI provider setup

Autumn billing setup (Optional)

Database schema

Scripts reference

Troubleshooting

Next steps

Quick start guide

Editor features

Deploy to production

Contributing

Additional resources

Build docs developers (and LLMs) love

Getting Started

Core Features

AI Features

Desktop App

Integrations

​Overview

​Prerequisites

Node.js

Package manager

Git

API accounts

​Required accounts

​Installation methods

​Install for web development

​Install Electron desktop app

​Configuration details

​Stack Auth setup

​Convex setup

​AI provider setup

​Autumn billing setup (Optional)

​Database schema

​Scripts reference

​Troubleshooting

​Next steps

Quick start guide

Editor features

Deploy to production

Contributing

​Additional resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Required accounts

Installation methods

Install for web development

Install Electron desktop app

Configuration details

Stack Auth setup

Convex setup

AI provider setup

Autumn billing setup (Optional)

Database schema

Scripts reference

Troubleshooting

Next steps

Additional resources