Skip to main content

​
Prerequisites

Before setting up Polaris IDE, ensure you have the following installed:

Node.js

Version 20.09 or higher required

Package Manager

npm or pnpm (bun also supported)

​
Required Accounts

You’ll need to create accounts with the following services:
Stack Auth provides authentication for Polaris IDE.
  1. Sign up at stack-auth.com
  2. Create a new project
  3. Copy your publishable and secret keys
Convex powers the real-time backend.
  1. Sign up at convex.dev
  2. Create a new project
  3. Run npx convex dev to get your deployment URL
Trigger.dev handles asynchronous task processing.
  1. Sign up at trigger.dev
  2. Create a new project
  3. Copy your API key from project settings
Choose one or both AI providers:OpenRouter (Recommended)
  • Sign up at openrouter.ai
  • Uses Moonshot AI Kimi K2.5 for superior code generation
Cerebras (Free Alternative)
Firecrawl - Web scraping for documentationSentry - Error tracking and monitoringAutumn - Subscription billing

​
Installation

1

Clone the repository

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

Install dependencies

npm install
# or
pnpm install
# or
bun install
3

Set up environment variables

Create a .env.local file in the project root:
.env.local
# Stack Auth - Authentication
NEXT_PUBLIC_STACK_PUBLISHABLE_KEY=your_publishable_key
STACK_SECRET_KEY=your_secret_key

# Convex - Real-time Database
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_DEPLOYMENT=your-deployment-name
POLARIS_CONVEX_INTERNAL_KEY=your_random_secure_string

# Trigger.dev - Background Jobs
TRIGGER_SECRET_KEY=your_trigger_secret_key

# AI Providers (at least one required)
OPENROUTER_API_KEY=sk-or-xxx  # Moonshot AI Kimi K2.5 (recommended)
CEREBRAS_API_KEY=csk-xxx  # Cerebras GLM-4.7 (free)

# Optional: Firecrawl
FIRECRAWL_API_KEY=your_firecrawl_key

# Optional: Sentry
SENTRY_DSN=your_sentry_dsn

# Optional: Autumn Billing
AUTUMN_SECRET_KEY=your_autumn_secret_key
NEXT_PUBLIC_AUTUMN_PRO_MONTHLY_PRODUCT_ID=prod_xxx
NEXT_PUBLIC_AUTUMN_PRO_YEARLY_PRODUCT_ID=prod_xxx
Generate a secure random string for POLARIS_CONVEX_INTERNAL_KEY using:
openssl rand -base64 32
4

Initialize Convex database

Start the Convex development server:
npx convex dev
This will:
  • Deploy your database schema
  • Generate TypeScript types
  • Provide a development URL for NEXT_PUBLIC_CONVEX_URL
Keep this terminal window open - Convex needs to run continuously
5

Start the Next.js development server

In a new terminal window:
npm run dev
The application will be available at http://localhost:3000
6

Start Trigger.dev development server

In another terminal window:
npm run dev:trigger
This enables background job processing for:
  • AI message processing
  • Project generation
  • File operations

​
Verify Installation

Once all three servers are running, verify your setup:
  • Next.js server running at http://localhost:3000
  • Convex dashboard accessible (check terminal output for URL)
  • Trigger.dev dashboard shows connected tasks
  • Authentication redirects to Stack Auth sign-in page

​
Development Workflow

​
Running Development Servers

You need three terminal windows for full development: 
npm run dev
Use a terminal multiplexer like tmux or tools like concurrently to manage multiple processes:
npm install -g concurrently
concurrently "npm run dev" "npx convex dev" "npm run dev:trigger"

​
Hot Reload Behavior

  • Frontend changes (.tsx, .ts in src/): Instant hot reload
  • Convex functions (.ts in convex/): Auto-deploy on save
  • Trigger.dev tasks (.ts in trigger/): Auto-reload on save
  • Environment variables: Requires server restart

​
Common Issues

Change the development port:
PORT=3001 npm run dev
Ensure your Stack Auth configuration matches:
  1. Check convex/auth.config.ts has correct project ID
  2. Verify NEXT_PUBLIC_STACK_PUBLISHABLE_KEY is set
  3. Clear browser cookies and try again
If you see errors about missing environment variables:
  1. Copy .env.example to .env.local
  2. Fill in all required values
  3. Restart all development servers
If Convex shows schema errors:
npx convex dev --once
npx convex dev

​
Next Steps

Architecture

Understand the system design and data flow

Contributing

Learn how to contribute to Polaris

Custom Extensions

Build your own CodeMirror extensions

Deployment

Deploy Polaris to production

Build docs developers (and LLMs) love

Get started for freeTalk to us