Integrations - Superset

Superset integrates with popular development tools to fit into your existing workflow. Open workspaces in your favorite editor, manage Git repositories, and connect to external services.

IDE Integration

Quickly open workspaces in external editors and IDEs.

Supported Editors

Superset automatically detects these editors on your system:

Visual Studio Code (code)
Cursor (cursor)
Sublime Text (subl)
IntelliJ IDEA (idea)
WebStorm (webstorm)
PyCharm (pycharm)
Vim/Neovim (vim, nvim)
Emacs (emacs)

Opening in External Editor

Configure Default Editor

Go to Settings > Editor Preferences and select your preferred editor. Or set the EDITOR environment variable:

export EDITOR="code"

Open Workspace

Press ⌘O to open the current workspace in your configured editor.

The workspace will open in a new editor window while keeping Superset running for terminal access and change monitoring.

Command Line

You can also open editors directly from the terminal:

# VS Code
code .

# Cursor
cursor .

# Sublime Text
subl .

# Vim
vim .

Git Integration

Superset is built around Git worktrees and provides seamless Git integration.

Built-in Git Features

Changes Panel (⌘L): View diffs, stage changes, and commit
Branch Isolation: Each workspace is a separate git worktree with its own branch
Status Indicators: See workspace status at a glance

Git Commands

All standard Git commands work in Superset terminals:

# View status
git status

# Create branch
git checkout -b feature/new-feature

# Commit changes
git add .
git commit -m "Implement feature"

# Push to remote
git push origin feature/new-feature

# View log
git log --oneline

# Merge branches
git merge main

Git Worktree Management

Superset manages worktrees automatically, but you can use Git worktree commands directly:

# List worktrees
git worktree list

# Add worktree manually
git worktree add ../my-workspace feature/my-branch

# Remove worktree
git worktree remove ../my-workspace

Deleting workspaces through Superset (⌘⇧Delete) properly cleans up worktrees and runs teardown scripts. Avoid manually deleting worktree directories.

GitHub CLI Integration

Use the GitHub CLI (gh) for managing issues, pull requests, and releases.

Installation

# macOS
brew install gh

# Authenticate
gh auth login

Common Commands

# Create PR
gh pr create --title "Add feature" --body "Description"

# List PRs
gh pr list

# View PR
gh pr view 123

# Checkout PR
gh pr checkout 123

# Merge PR
gh pr merge 123 --squash

GitHub Actions

Monitor CI/CD workflows:

# View workflow runs
gh run list

# Watch latest run
gh run watch

# View run logs
gh run view 789 --log

Caddy Integration

Superset uses Caddy as an HTTP/2 reverse proxy for Electric SQL streams.

Why Caddy?

Browsers limit concurrent HTTP/1.1 connections to 6 per domain. When running multiple Electric SQL shape streams, this becomes a bottleneck. Caddy provides HTTP/2 multiplexing to bypass this limit.

Installation

# macOS
brew install caddy

# Trust Caddy's certificate for HTTPS
sudo caddy trust

Configuration

Superset automatically generates a Caddyfile during workspace setup:

Caddyfile

https://localhost:{$CADDY_ELECTRIC_PORT} {
  reverse_proxy localhost:{$API_PORT} {
    flush_interval -1
  }
}

Starting Caddy

# Start Caddy (usually in setup script)
caddy start --config Caddyfile

# Stop Caddy (usually in teardown script)
caddy stop

Caddy runs on port SUPERSET_PORT_BASE + 10 by default (e.g., 3010 for base port 3000).

Docker Integration

Run Docker containers alongside your workspaces for databases, caches, and services.

Starting Containers in Setup Scripts

.superset/setup.sh

#!/bin/bash

# Start PostgreSQL
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-db" \
  -e POSTGRES_PASSWORD=dev \
  -p 5432:5432 \
  postgres:16

# Start Redis
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-redis" \
  -p 6379:6379 \
  redis:7-alpine

# Start Electric SQL
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-electric" \
  -p 3000:3000 \
  -e DATABASE_URL="$DATABASE_URL" \
  electricsql/electric:latest

Stopping Containers in Teardown Scripts

.superset/teardown.sh

#!/bin/bash

# Stop and remove all workspace containers
docker stop "${SUPERSET_WORKSPACE_NAME}-db" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-db" 2>/dev/null || true

docker stop "${SUPERSET_WORKSPACE_NAME}-redis" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-redis" 2>/dev/null || true

docker stop "${SUPERSET_WORKSPACE_NAME}-electric" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-electric" 2>/dev/null || true

Managing Containers from Terminal

# List running containers
docker ps

# View logs
docker logs ${SUPERSET_WORKSPACE_NAME}-db

# Follow logs
docker logs -f ${SUPERSET_WORKSPACE_NAME}-db

# Execute commands in container
docker exec -it ${SUPERSET_WORKSPACE_NAME}-db psql -U postgres

# Restart container
docker restart ${SUPERSET_WORKSPACE_NAME}-db

Database Service Integration

Connect to managed database services like Neon, PlanetScale, and Supabase.

Neon

Superset’s setup scripts can automatically create database branches using Neon:

# Create branch
BRANCH_ID=$(neonctl branches create \
  --project-id "$NEON_PROJECT_ID" \
  --name "$SUPERSET_WORKSPACE_NAME" \
  --output json | jq -r '.branch.id')

# Get connection string
DATABASE_URL=$(neonctl connection-string "$BRANCH_ID" \
  --project-id "$NEON_PROJECT_ID" \
  --pooled)

echo "DATABASE_URL=$DATABASE_URL" >> .env

See the Setup/Teardown Scripts guide for more examples.

PlanetScale

Create branches for MySQL databases:

# Create branch
pscale branch create my-database "$SUPERSET_WORKSPACE_NAME"

# Get connection string
DATABASE_URL=$(pscale connect my-database "$SUPERSET_WORKSPACE_NAME" --format json | jq -r .url)

Supabase

Use Supabase CLI for local development:

# Initialize Supabase
supabase init

# Start local Supabase
supabase start

# Get connection string
supabase status | grep "DB URL"

External Tool Launching

Launch external tools from Superset terminals.

Browser

Open URLs in your default browser:

# macOS
open http://localhost:3000

# Linux
xdg-open http://localhost:3000

# Windows
start http://localhost:3000

Database Clients

# Postico (PostgreSQL GUI for macOS)
open -a Postico "postgres://localhost:5432/mydb"

# TablePlus
open -a TablePlus "postgres://localhost:5432/mydb"

# psql (command line)
psql "$DATABASE_URL"

API Clients

# Postman
open -a Postman

# Insomnia
open -a Insomnia

# HTTPie (CLI)
http GET localhost:3000/api/users

Custom Integrations

Build your own integrations using Superset’s MCP server.

Available Tools

The Superset MCP server provides tools for:

Creating workspaces
Switching workspaces
Listing workspaces
Updating workspace metadata
Deleting workspaces
Managing tasks

See the MCP Servers guide for details.

Example: Custom CLI Tool

superset-cli.sh

#!/bin/bash
# Custom CLI tool that uses Superset MCP

SUPERSET_API="http://localhost:3001/api/agent/mcp"

case "$1" in
  create)
    curl -X POST "$SUPERSET_API/workspaces" \
      -H "Content-Type: application/json" \
      -d '{"name": "'"$2"'", "projectId": "'"$3"'"}'
    ;;
  list)
    curl -X GET "$SUPERSET_API/workspaces"
    ;;
  *)
    echo "Usage: $0 {create|list} [args]"
    exit 1
    ;;
esac

Environment Variables

Integrations often require environment variables. Manage them in your .env file:

.env

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Neon
NEON_PROJECT_ID=xxx-xxx-xxx
NEON_API_KEY=xxxxxxxx

# Docker
DOCKER_HOST=unix:///var/run/docker.sock

# Editor
EDITOR=code

Never commit .env files to Git. Add .env to your .gitignore.

Troubleshooting

Editor command not found

If ⌘O fails to open your editor:

Make sure the editor is installed
Check that the command is in your PATH: which code
Set the EDITOR environment variable manually
Try running the command in terminal first

GitHub CLI not authenticated

If gh commands fail:

Run gh auth login
Follow the authentication flow
Verify: gh auth status

Docker containers won't start

If Docker commands fail:

Make sure Docker Desktop is running
Check Docker status: docker ps
Verify port availability: lsof -i :5432
Check logs: docker logs <container-name>

Caddy certificate errors

If HTTPS connections fail:

Trust Caddy’s certificate: sudo caddy trust
Restart Caddy
Check Caddy status: caddy status

Setup Scripts

Automate integrations with setup scripts

MCP Servers

Build integrations using MCP

Workspace Management

Learn how workspaces work

Documentation Index

​IDE Integration

​Supported Editors

​Opening in External Editor

​Command Line

​Git Integration

​Built-in Git Features

​Git Commands

​Git Worktree Management

​GitHub CLI Integration

​Installation

​Common Commands

​GitHub Actions

​Caddy Integration

​Why Caddy?

​Installation

​Configuration

​Starting Caddy

​Docker Integration

​Starting Containers in Setup Scripts

​Stopping Containers in Teardown Scripts

​Managing Containers from Terminal

​Database Service Integration

​Neon

​PlanetScale

​Supabase

​External Tool Launching

​Browser

​Database Clients

​API Clients

​Custom Integrations

​Available Tools

​Example: Custom CLI Tool

​Environment Variables

​Troubleshooting

​Related Topics

Setup Scripts

MCP Servers

Workspace Management

IDE Integration

Supported Editors

Opening in External Editor

Command Line

Git Integration

Built-in Git Features

Git Commands

Git Worktree Management

GitHub CLI Integration

Installation

Common Commands

GitHub Actions

Caddy Integration

Why Caddy?

Installation

Configuration

Starting Caddy

Docker Integration

Starting Containers in Setup Scripts

Stopping Containers in Teardown Scripts

Managing Containers from Terminal

Database Service Integration

Neon

PlanetScale

Supabase

External Tool Launching

Browser

Database Clients

API Clients

Custom Integrations

Available Tools

Example: Custom CLI Tool

Environment Variables

Troubleshooting

Related Topics