> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/superset-sh/superset/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://bun.sh/) v1.0+                                         |
| **Version control**  | Git 2.20+                                                            |
| **GitHub CLI**       | [gh](https://cli.github.com/)                                        |
| **Reverse proxy**    | [Caddy](https://caddyserver.com/docs/install) (for development only) |

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

## Quick start: Pre-built app

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

<Steps>
  <Step title="Download the latest release">
    Visit the [Superset releases page](https://github.com/superset-sh/superset/releases/latest) and download the latest `.dmg` file for macOS.

    ```bash theme={null}
    # Or download via curl
    curl -L https://github.com/superset-sh/superset/releases/latest/download/Superset.dmg -o Superset.dmg
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Info>
      Your account lets you access workspaces across devices and enables team collaboration features.
    </Info>
  </Step>

  <Step title="Verify installation">
    After signing in, you should see the main Superset interface. You're ready to create your first workspace!

    <Tip>
      Press `⌘N` to create your first workspace and get started.
    </Tip>
  </Step>
</Steps>

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

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  # 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
  ```

  ```bash Linux theme={null}
  # Install Bun
  curl -fsSL https://bun.sh/install | bash

  # Install Git
  sudo apt-get install git  # Debian/Ubuntu
  sudo yum install git       # RHEL/CentOS

  # Install GitHub CLI
  # See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md

  # Install Caddy
  # See: https://caddyserver.com/docs/install#debian-ubuntu-raspbian
  ```
</CodeGroup>

<Info>
  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"`).
</Info>

### Build steps

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/superset-sh/superset.git
    cd superset
    ```
  </Step>

  <Step title="Set up environment variables">
    Copy the example environment file and configure it for your setup:

    <Tabs>
      <Tab title="Full setup">
        For production-like setup with all services:

        ```bash theme={null}
        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](#environment-variables) below for details.
      </Tab>

      <Tab title="Quick local testing">
        For local development without external services:

        ```bash theme={null}
        cp .env.example .env
        echo 'SKIP_ENV_VALIDATION=1' >> .env
        ```

        <Warning>
          This skips environment validation and is only recommended for quick local testing. Some features may not work without proper configuration.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Caddy reverse proxy">
    Caddy is used as a reverse proxy for Electric SQL streams during development:

    ```bash theme={null}
    cp Caddyfile.example Caddyfile
    ```

    <Info>
      The default Caddyfile configuration works for local development. You typically don't need to modify it.
    </Info>
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    bun install
    ```

    This installs all dependencies for the monorepo using Bun's fast installer.
  </Step>

  <Step title="Run in development mode">
    Start the development server:

    ```bash theme={null}
    bun run dev
    ```

    This starts:

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

    The desktop app will launch automatically.
  </Step>

  <Step title="Build production app">
    To create a production build:

    ```bash theme={null}
    bun run build
    ```

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

    ```bash theme={null}
    # Open the release directory
    open apps/desktop/release
    ```
  </Step>
</Steps>

## Environment variables

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

<AccordionGroup>
  <Accordion title="Database (Neon PostgreSQL)">
    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Authentication (Better Auth)">
    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Development URLs">
    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Analytics & Monitoring">
    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="MCP API Key">
    ```bash theme={null}
    # 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.
  </Accordion>
</AccordionGroup>

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

## Verification

After installation, verify everything is working:

<Steps>
  <Step title="Launch Superset">
    Open the Superset application from your Applications folder or by running `bun run dev` if building from source.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Create a test workspace">
    Press `⌘N` to create a new workspace. This verifies:

    * Git worktree creation works
    * Terminal spawning works
    * Setup scripts execute properly
  </Step>
</Steps>

## Troubleshooting

Common installation issues and solutions:

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    xattr -cr /Applications/Superset.app
    ```
  </Accordion>

  <Accordion title="Build fails with 'bun: command not found'">
    **Problem:** Bun is not installed or not in your PATH.

    **Solution:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Git worktree creation fails">
    **Problem:** Git version is too old or worktrees aren't supported.

    **Solution:**
    Update Git to version 2.20 or later:

    ```bash theme={null}
    # macOS
    brew upgrade git

    # Linux
    sudo apt-get update && sudo apt-get upgrade git
    ```
  </Accordion>

  <Accordion title="Caddy fails to start in development">
    **Problem:** Port 80 or 443 is already in use, or Caddy isn't installed.

    **Solution:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Environment validation errors">
    **Problem:** Missing required environment variables during build.

    **Solution:**
    For local development, skip validation:

    ```bash theme={null}
    echo 'SKIP_ENV_VALIDATION=1' >> .env
    ```

    For production, ensure all required variables in `.env.example` are set in your `.env` file.
  </Accordion>
</AccordionGroup>

<Note>
  For more troubleshooting help, see the [Troubleshooting guide](/resources/troubleshooting) or ask in our [Discord community](https://discord.gg/cZeD9WYcV7).
</Note>

## Next steps

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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first workspace and run an agent in under 5 minutes
  </Card>

  <Card title="Keyboard shortcuts" icon="keyboard" href="/guides/keyboard-shortcuts">
    Learn essential shortcuts for productive workflow
  </Card>

  <Card title="Setup scripts" icon="file-code" href="/guides/setup-teardown-scripts">
    Automate workspace setup with custom scripts
  </Card>

  <Card title="Configuration" icon="gear" href="/concepts/configuration">
    Configure Superset for your workflow
  </Card>
</CardGroup>