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

> Install Apache Superset from source using the Bun monorepo. Clone the superset-sh superset repository configure environment variables install dependencies and run the dev server.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/superset-sh/superset/blob/main/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:

```bash
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:

```bash
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)**

```bash
cp .env.example .env

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

```

**Option B: Quick development mode**

```bash
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:

```bash

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

```bash
bun install

```

This command reads the `packageManager` field from [`package.json`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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:

```bash
bun run dev

```

This executes the `dev` script defined in the root [`package.json`](https://github.com/superset-sh/superset/blob/main/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:

```bash
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:

```bash

# 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`](https://github.com/superset-sh/superset/blob/main/README.md) | Main documentation and installation guide | Repository root |
| `.env.example` | Template for all environment variables | Repository root |
| [`package.json`](https://github.com/superset-sh/superset/blob/main/package.json) | Monorepo configuration, Bun version requirement, dev scripts | Repository root |
| [`apps/web/package.json`](https://github.com/superset-sh/superset/blob/main/apps/web/package.json) | Web application dependencies and scripts | `apps/web/` |
| `Caddyfile.example` | Reverse proxy configuration for streaming | Repository root |
| [`.superset/setup.sh`](https://github.com/superset-sh/superset/blob/main/.superset/setup.sh) | Workspace setup logic for new worktrees | `.superset/` |
| `turbo.jsonc` | Turbo Repo pipeline configuration | Repository root |
| [`scripts/postinstall.sh`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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.