Skip to main content

​
System requirements

Before installing Superset, ensure your system meets these requirements:
RequirementDetails
Operating systemmacOS (Windows/Linux untested)
RuntimeBun v1.0+
Version controlGit 2.20+
GitHub CLIgh
Reverse proxyCaddy (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: 
# 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": "[email protected]").

​
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:
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.
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: 
# 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.
# 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.
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.
# 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.
# 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:
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
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
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
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us