Installation

Install Superset on macOS via pre-built app or build from source

System requirements

Before installing Superset, ensure your system meets these requirements:

Requirement	Details
Operating system	macOS (Windows/Linux untested)
Runtime	Bun v1.0+
Version control	Git 2.20+
GitHub CLI	gh
Reverse proxy	Caddy (for development only)

Superset is currently optimized for macOS. While it may work on Windows and Linux, these platforms are untested and may have issues.

Quick start: Pre-built app

The fastest way to get started with Superset is to download the pre-built macOS application.

1. Download the latest release

   Visit the Superset releases page and download the latest .dmg file for macOS.

   # Or download via curl
   curl -L https://github.com/superset-sh/superset/releases/latest/download/Superset.dmg -o Superset.dmg
   
2. Install the application

   1. Open the downloaded .dmg file
   2. Drag the Superset app to your Applications folder
   3. Launch Superset from Applications or Spotlight
3. Grant necessary permissions

   On first launch, macOS may ask for permissions:

   • Accessibility — Required for keyboard shortcuts
   • File system access — Required to manage workspaces

   Grant these permissions when prompted.

4. Sign in or create an account

   When you first launch Superset, you’ll be prompted to sign in or create an account. Authentication is required to use the desktop app and sync your workspaces.

   Your account lets you access workspaces across devices and enables team collaboration features.

5. Verify installation

   After signing in, you should see the main Superset interface. You’re ready to create your first workspace!

   Press ⌘N to create your first workspace and get started.

Build from source

For contributors or users who want the latest development version, you can build Superset from source.

Prerequisites

Install the required dependencies before building:

macOS (Homebrew)

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install Git (if not already installed)
brew install git

# Install GitHub CLI
brew install gh

# Install Caddy (for development server)
brew install caddy

Bun is required for this project. The repository uses Bun as its package manager and runtime (see package.json which specifies "packageManager": "bun@1.3.6").

Build steps

1. Clone the repository

   git clone https://github.com/superset-sh/superset.git
   cd superset
   
2. Set up environment variables

   Copy the example environment file and configure it for your setup:

   Full setup

   For production-like setup with all services:

   cp .env.example .env
   # Edit .env and fill in the required values
   

   Open .env in your editor and configure:

   • Database credentials (Neon PostgreSQL)
   • OAuth credentials (Google, GitHub)
   • API keys (PostHog, Sentry, etc.)

   See the .env.example reference below for details.

   Quick local testing

   For local development without external services:

   cp .env.example .env
   echo 'SKIP_ENV_VALIDATION=1' >> .env
   

   This skips environment validation and is only recommended for quick local testing. Some features may not work without proper configuration.

3. Configure Caddy reverse proxy

   Caddy is used as a reverse proxy for Electric SQL streams during development:

   cp Caddyfile.example Caddyfile
   

   The default Caddyfile configuration works for local development. You typically don’t need to modify it.

4. Install dependencies

   bun install
   

   This installs all dependencies for the monorepo using Bun’s fast installer.

5. Run in development mode

   Start the development server:

   bun run dev
   

   This starts:

   • Desktop app with hot reload
   • API server
   • Web app
   • Caddy reverse proxy

   The desktop app will launch automatically.

6. Build production app

   To create a production build:

   bun run build
   

   This compiles the desktop app and creates a distributable package in apps/desktop/release/.

   # Open the release directory
   open apps/desktop/release
   

Environment variables

The .env.example file contains all configurable environment variables. Key variables include:

Database (Neon PostgreSQL)

# Neon organization and project
NEON_ORG_ID=your_org_id
NEON_PROJECT_ID=your_project_id
NEON_API_KEY=your_api_key

# Database connection strings
DATABASE_URL=postgresql://...
DATABASE_URL_UNPOOLED=postgresql://...

Required for cloud sync features. Local-only usage doesn’t require these.

Authentication (Better Auth)

# Auth secret for session encryption
BETTER_AUTH_SECRET=generate_random_string_here
NEXT_PUBLIC_COOKIE_DOMAIN=localhost

# OAuth providers
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GH_CLIENT_ID=your_github_client_id
GH_CLIENT_SECRET=your_github_client_secret

Required for user authentication in the desktop app.

Development URLs

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WEB_URL=http://localhost:3000
NEXT_PUBLIC_ADMIN_URL=http://localhost:3003
NEXT_PUBLIC_MARKETING_URL=http://localhost:3002
NEXT_PUBLIC_DOCS_URL=http://localhost:3004

Default local development URLs. Typically don’t need changes.

Analytics & Monitoring

# PostHog analytics
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
POSTHOG_API_KEY=your_api_key
POSTHOG_PROJECT_ID=your_project_id

# Sentry error tracking
SENTRY_AUTH_TOKEN=your_sentry_token
NEXT_PUBLIC_SENTRY_ENVIRONMENT=development
SENTRY_DSN_DESKTOP=your_desktop_dsn

Optional. Used for telemetry and error tracking.

MCP API Key

# API key for Claude Code MCP integration
SUPERSET_MCP_API_KEY=your_mcp_api_key

Optional. Required only if using Model Context Protocol with Claude Code.

For local development, you can use SKIP_ENV_VALIDATION=1 to bypass environment variable validation. However, certain features may not work without proper configuration.

Verification

After installation, verify everything is working:

1. Launch Superset

   Open the Superset application from your Applications folder or by running bun run dev if building from source.

2. Check system requirements

   Superset will automatically check for required dependencies:

   • Git installation
   • GitHub CLI (gh)
   • Bun runtime (for source builds)

   If any are missing, you’ll see a warning in the app.

3. Create a test workspace

   Press ⌘N to create a new workspace. This verifies:

   • Git worktree creation works
   • Terminal spawning works
   • Setup scripts execute properly

Troubleshooting

Common installation issues and solutions:

App won't open on macOS

Problem: macOS blocks the app because it’s from an unidentified developer.

Solution:

1. Right-click the Superset app in Applications
2. Select Open from the context menu
3. Click Open in the security dialog

Or use the command line:

xattr -cr /Applications/Superset.app

Build fails with 'bun: command not found'

Problem: Bun is not installed or not in your PATH.

Solution:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# Reload shell
source ~/.zshrc  # or source ~/.bashrc

Git worktree creation fails

Problem: Git version is too old or worktrees aren’t supported.

Solution: Update Git to version 2.20 or later:

# macOS
brew upgrade git

# Linux
sudo apt-get update && sudo apt-get upgrade git

Caddy fails to start in development

Problem: Port 80 or 443 is already in use, or Caddy isn’t installed.

Solution:

# Install Caddy if missing
brew install caddy

# Check if ports are in use
sudo lsof -i :80
sudo lsof -i :443

# Kill conflicting processes or modify Caddyfile to use different ports

Environment validation errors

Problem: Missing required environment variables during build.

Solution: For local development, skip validation:

echo 'SKIP_ENV_VALIDATION=1' >> .env

For production, ensure all required variables in .env.example are set in your .env file.

For more troubleshooting help, see the Troubleshooting guide or ask in our Discord community.

Next steps

Now that Superset is installed, get started with your first workspace:

Quickstart

Create your first workspace and run an agent in under 5 minutes

Keyboard shortcuts

Learn essential shortcuts for productive workflow

Setup scripts

Automate workspace setup with custom scripts

Configuration

Configure Superset for your workflow