How to Install Superset (Terminal) from Source: Complete Bun Monorepo Guide

To install Superset from source, clone the superset-sh/superset repository, configure your environment variables, install dependencies with Bun, and run the development server.

Superset is a turbo-charged terminal for running CLI-based coding agents, built as a Bun and Turbo monorepo. Installing from source gives you access to the latest features, the ability to customize the web and desktop apps, and full control over the development environment. This guide walks through the exact steps derived from the official repository source files.

Prerequisites

Before cloning the repository, ensure your system meets the following requirements. The project is strictly managed by Bun, and several optional tools enhance the streaming backend functionality.

Tool	Version	Purpose	Documentation
Bun	v1.3.6 or newer	Package manager and runtime (specified in package.json → packageManager)	https://bun.sh/
Git	2.20+	Clone the repository and manage worktrees	https://git-scm.com/
GitHub CLI (gh)	any	Used by Superset scripts for repository-wide actions	https://cli.github.com/
Caddy (optional)	latest	Reverse proxy required for Electric SQL streaming backend	https://caddyserver.com/docs/install

If you encounter a "command not found: bun" error, install Bun first:

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

Step-by-Step Installation

Clone the Repository

Start by cloning the monorepo and navigating into the project directory:

git clone https://github.com/superset-sh/superset.git
cd superset

This creates a local copy of the superset-sh/superset repository, which contains the web app, desktop app, and shared packages managed by Turbo.

Configure Environment Variables

Superset requires specific environment variables to connect to databases and external services. You can either configure these properly or skip validation for a quick local test.

Option A: Full setup (recommended for production)

cp .env.example .env

# Edit .env with your actual API keys and database URLs

Option B: Quick development mode

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

The .env.example file in the repository root defines all required variables, including Neon database connection strings and Electric SQL configuration.

Install Caddy (Optional)

If you plan to use the Electric SQL streaming features, install and configure Caddy:

# macOS example

brew install caddy
cp Caddyfile.example Caddyfile

The Caddyfile.example provides the reverse proxy configuration needed for the streaming backend. Without Caddy, the core terminal and web interface still function, but real-time collaboration features are disabled.

Install Dependencies

With Bun installed and the environment configured, install all monorepo dependencies:

bun install

This command reads the packageManager field from package.json (which specifies bun@1.3.6) and installs dependencies for all workspaces defined in the monorepo, including apps/web and apps/desktop. The scripts/postinstall.sh runs automatically after installation to finalize local package linking.

Run the Development Server

Start the entire development stack with a single command:

bun run dev

This executes the dev script defined in the root package.json, which triggers Turbo to run the development pipelines for the web application, API server, and Caddy proxy simultaneously. The terminal will display logs from all concurrent processes.

Build the Desktop Application (Optional)

To create a distributable desktop app instead of running the web version:

bun run build
open apps/desktop/release

The build command compiles the desktop application using the configuration in apps/desktop. The resulting binaries appear in apps/desktop/release, ready for installation on your local machine.

Complete Installation Script

For automation or quick reference, here is the full workflow in a single script:

# 1. Clone repository

git clone https://github.com/superset-sh/superset.git
cd superset

# 2. Configure environment (quick-dev mode)

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

# 3. Install Caddy (optional, for streaming features)

brew install caddy
cp Caddyfile.example Caddyfile

# 4. Install dependencies

bun install

# 5. Start development server

bun run dev

# 6. Build desktop app (optional)

# bun run build && open apps/desktop/release

Key Source Files Reference

Understanding the repository structure helps when troubleshooting or customizing the installation.

File	Purpose	Location
README.md	Main documentation and installation guide	Repository root
.env.example	Template for all environment variables	Repository root
package.json	Monorepo configuration, Bun version requirement, dev scripts	Repository root
apps/web/package.json	Web application dependencies and scripts	apps/web/
Caddyfile.example	Reverse proxy configuration for streaming	Repository root
.superset/setup.sh	Workspace setup logic for new worktrees	.superset/
turbo.jsonc	Turbo Repo pipeline configuration	Repository root
scripts/postinstall.sh	Post-installation hooks for local package linking	scripts/

Summary

• Superset is a Bun-based monorepo requiring Bun v1.3.6+ and Git for source installation.
• Clone from https://github.com/superset-sh/superset.git and copy .env.example to .env before installing.
• Use SKIP_ENV_VALIDATION=1 for quick local testing without database connections.
• Run bun install to install monorepo dependencies and bun run dev to start the development server.
• Optional Caddy installation enables Electric SQL streaming features.
• Build desktop applications with bun run build, which outputs to apps/desktop/release.

Frequently Asked Questions

Do I need a Neon database to run Superset locally?

No. While the .env.example file includes Neon database connection strings for production deployments, you can run Superset locally without any external database. Set SKIP_ENV_VALIDATION=1 in your .env file to bypass validation and run the terminal in standalone mode.

Can I run the repository without installing Caddy?

Yes. Caddy is only required if you intend to use the Electric SQL streaming backend features. The core web interface and terminal functionality work without Caddy. Simply omit the Caddy configuration steps and run bun run dev to start only the web and API servers.

What should I do if I get a "command not found: bun" error?

Install Bun using the official installer: curl -fsSL https://bun.sh/install | bash. The Superset monorepo specifically requires Bun version 1.3.6 or newer, as defined in the packageManager field of package.json. After installation, restart your terminal and verify the version with bun --version.

How do I create a production build of the desktop application?

Run bun run build from the repository root. This command triggers the Turbo pipeline to compile the desktop application using the configuration in apps/desktop. The resulting distributable files appear in apps/desktop/release, ready for installation on macOS, Windows, or Linux depending on your build configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}