Configuration - Superset

Overview

Superset allows you to automate workspace initialization and cleanup through configuration files. The .superset/config.json file in your repository root defines scripts that run when workspaces are created or deleted.

Configuration is per-repository. Each project can have its own setup and teardown logic.

.superset/config.json Format

The configuration file uses a simple JSON structure:

{
  "setup": ["./path/to/script1.sh", "./path/to/script2.sh"],
  "teardown": ["./path/to/cleanup.sh"]
}

Field	Type	Description
`setup`	`string[]`	Scripts to run when creating a workspace
`teardown`	`string[]`	Scripts to run when deleting a workspace

Scripts are executed in order. If a script fails, subsequent scripts still run.

Setup Scripts

Setup scripts run automatically when a workspace is created, before any presets execute.

When Setup Scripts Run

User creates a workspace (⌘N or ⌘⇧N)
Superset creates git worktree
Setup scripts execute ← You are here
Terminal session starts
Presets execute (if configured)

Example Setup Script

Here’s a typical setup script that prepares a workspace:

#!/usr/bin/env bash
# .superset/setup.sh

set -euo pipefail

# Copy environment variables from main repo
echo "Copying .env file..."
cp "$SUPERSET_ROOT_PATH/.env" .env

# Install dependencies
echo "Installing dependencies..."
bun install

# Run database migrations
echo "Running migrations..."
bun run db:migrate

# Seed test data (optional)
if [ "$SUPERSET_WORKSPACE_NAME" = "test-workspace" ]; then
  echo "Seeding test data..."
  bun run db:seed
fi

echo "✓ Workspace setup complete!"

Make your setup scripts executable: chmod +x .superset/setup.sh

Common Setup Tasks

Copy .env Files

cp "$SUPERSET_ROOT_PATH/.env" .env

Git ignores .env, so copy it from the main repo.

Install Dependencies

bun install
# or: npm install, yarn, pnpm install

Each worktree needs its own node_modules.

Database Migrations

bun run db:migrate

Ensure database schema is up to date.

Build Assets

bun run build

Pre-build assets if needed.

Teardown Scripts

Teardown scripts run when a workspace is deleted, before the git worktree is removed.

When Teardown Scripts Run

User deletes workspace
Superset closes terminal sessions
Teardown scripts execute ← You are here
Git worktree is removed
Workspace metadata cleaned up

Example Teardown Script

#!/usr/bin/env bash
# .superset/teardown.sh

set -euo pipefail

echo "Cleaning up workspace: $SUPERSET_WORKSPACE_NAME"

# Stop running services
if [ -f .pid ]; then
  echo "Stopping background services..."
  kill $(cat .pid) 2>/dev/null || true
  rm .pid
fi

# Clean temporary files
echo "Removing temporary files..."
rm -rf .tmp/ *.log

# Archive important data
if [ -d data/ ]; then
  echo "Archiving data..."
  tar -czf "$SUPERSET_ROOT_PATH/archives/$SUPERSET_WORKSPACE_NAME.tar.gz" data/
fi

echo "✓ Workspace cleanup complete!"

Common Teardown Tasks

Stop Services

pkill -f "my-dev-server" || true

Kill long-running processes.

Clean Temp Files

rm -rf .tmp/ *.log node_modules/.cache/

Remove temporary data.

Archive Data

tar -czf ~/archives/data.tar.gz data/

Save important files before deletion.

Cleanup Docker

docker-compose down

Stop and remove containers.

Environment Variables in Scripts

Scripts run with special environment variables provided by Superset:

Variable	Description	Example
`SUPERSET_WORKSPACE_NAME`	Name of the workspace	`"add-oauth-integration"`
`SUPERSET_ROOT_PATH`	Absolute path to main repository	`"/Users/you/projects/my-app"`

Using Environment Variables

#!/usr/bin/env bash
# .superset/setup.sh

echo "Setting up workspace: $SUPERSET_WORKSPACE_NAME"
echo "Main repository: $SUPERSET_ROOT_PATH"

# Copy files from main repo
cp "$SUPERSET_ROOT_PATH/.env" .env
cp "$SUPERSET_ROOT_PATH/.env.local" .env.local

# Workspace-specific configuration
if [[ "$SUPERSET_WORKSPACE_NAME" == *"production"* ]]; then
  echo "Using production configuration"
  cp "$SUPERSET_ROOT_PATH/.env.production" .env
fi

Don’t rely on $PWD or relative paths. Use $SUPERSET_ROOT_PATH to reference the main repository.

Real Configuration Examples

Example 1: Node.js Project

{
  "setup": ["./.superset/setup.sh"],
  "teardown": ["./.superset/teardown.sh"]
}

Setup script:

#!/usr/bin/env bash
set -euo pipefail

# Copy environment
cp "$SUPERSET_ROOT_PATH/.env" .env

# Install dependencies
bun install

# Build packages
bun run build

echo "✓ Ready to code!"

Teardown script:

#!/usr/bin/env bash
set -euo pipefail

echo "Cleaning up $SUPERSET_WORKSPACE_NAME"

# Remove node_modules to save space
rm -rf node_modules

echo "✓ Cleanup complete"

Example 2: Python Project with Database

{
  "setup": [
    "./.superset/scripts/setup-venv.sh",
    "./.superset/scripts/setup-db.sh"
  ],
  "teardown": ["./.superset/scripts/cleanup.sh"]
}

setup-venv.sh:

#!/usr/bin/env bash
set -euo pipefail

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

echo "✓ Virtual environment ready"

setup-db.sh:

#!/usr/bin/env bash
set -euo pipefail

source venv/bin/activate

# Run migrations
flask db upgrade

# Seed test data
flask seed

echo "✓ Database ready"

cleanup.sh:

#!/usr/bin/env bash
set -euo pipefail

# Drop test database
flask db-drop || true

# Remove virtual environment
rm -rf venv

echo "✓ Cleanup complete"

Example 3: Docker Compose Project

{
  "setup": ["./.superset/docker-setup.sh"],
  "teardown": ["./.superset/docker-teardown.sh"]
}

docker-setup.sh:

#!/usr/bin/env bash
set -euo pipefail

# Copy environment
cp "$SUPERSET_ROOT_PATH/.env" .env

# Allocate unique port for this workspace
PORT_BASE=$((8000 + $(echo "$SUPERSET_WORKSPACE_NAME" | md5sum | grep -oE '[0-9]+' | head -1 | cut -c1-3)))
echo "PORT=$PORT_BASE" >> .env

# Start services
docker-compose up -d

echo "✓ Services running on port $PORT_BASE"

docker-teardown.sh:

#!/usr/bin/env bash
set -euo pipefail

# Stop and remove containers
docker-compose down -v

echo "✓ Services stopped"

Example 4: Monorepo with Selective Install

{
  "setup": ["./.superset/monorepo-setup.sh"],
  "teardown": ["./.superset/monorepo-cleanup.sh"]
}

monorepo-setup.sh:

#!/usr/bin/env bash
set -euo pipefail

# Determine which packages to install based on workspace name
if [[ "$SUPERSET_WORKSPACE_NAME" == *"frontend"* ]]; then
  echo "Installing frontend dependencies only"
  cd apps/web && bun install
elif [[ "$SUPERSET_WORKSPACE_NAME" == *"api"* ]]; then
  echo "Installing API dependencies only"
  cd apps/api && bun install
else
  echo "Installing all dependencies"
  bun install
fi

echo "✓ Dependencies installed"

Example 5: Multi-Stage Setup

{
  "setup": [
    "./.superset/stages/01-dependencies.sh",
    "./.superset/stages/02-database.sh",
    "./.superset/stages/03-build.sh",
    "./.superset/stages/04-verify.sh"
  ],
  "teardown": ["./.superset/cleanup.sh"]
}

This approach breaks setup into logical stages, making it easier to debug issues.

Script Best Practices

Use set -euo pipefail

Start scripts with:

#!/usr/bin/env bash
set -euo pipefail

Exits on error, unset variables, and pipe failures.

Provide Feedback

echo "Installing dependencies..."
bun install
echo "✓ Dependencies installed"

Let users know what’s happening.

Handle Failures Gracefully

command || echo "Warning: command failed"
optional-cleanup || true

Don’t break setup for non-critical failures.

Make Scripts Idempotent

[ -d venv ] || python3 -m venv venv

Safe to run multiple times without side effects.

Error Handling

Handle errors gracefully to prevent setup failures:

#!/usr/bin/env bash
set -euo pipefail

# Critical: exit if this fails
cp "$SUPERSET_ROOT_PATH/.env" .env

# Optional: continue if this fails
optional-command || echo "Warning: optional-command failed (continuing)"

# Always runs even if previous command fails
trap "echo 'Setup incomplete but workspace is usable'" EXIT

Performance Optimization

#!/usr/bin/env bash
set -euo pipefail

# Only install if package.json changed
if [ ! -d node_modules ] || [ package.json -nt node_modules ]; then
  echo "Installing dependencies..."
  bun install
else
  echo "Dependencies up to date, skipping install"
fi

Debugging Scripts

If setup or teardown scripts fail:

1. Check Script Output

Superset shows script output in the workspace creation dialog. Look for error messages.

2. Run Scripts Manually

Test scripts in a terminal:

cd ~/.superset/worktrees/my-project/test-workspace
export SUPERSET_WORKSPACE_NAME="test-workspace"
export SUPERSET_ROOT_PATH="$HOME/projects/my-project"
bash .superset/setup.sh

3. Add Debug Output

#!/usr/bin/env bash
set -euo pipefail
set -x  # Enable debug output

echo "DEBUG: SUPERSET_WORKSPACE_NAME=$SUPERSET_WORKSPACE_NAME"
echo "DEBUG: SUPERSET_ROOT_PATH=$SUPERSET_ROOT_PATH"
echo "DEBUG: PWD=$PWD"

# Your script logic...

4. Check Permissions

# Make scripts executable
chmod +x .superset/*.sh
chmod +x .superset/scripts/*.sh

Configuration Validation

Superset validates .superset/config.json when loading a project:

✅ Valid JSON syntax
✅ setup and teardown are arrays of strings
✅ Script paths are relative (not absolute)
⚠️ Warning if script files don’t exist
⚠️ Warning if scripts aren’t executable

Common mistake: Using absolute paths in config.json. Always use relative paths:✅ Good: "./.superset/setup.sh"❌ Bad: "/Users/you/project/.superset/setup.sh"

Relationship with Presets

Setup scripts run before presets:

Workspace Creation Flow:
Create git worktree
Run setup scripts     ← Prepare environment
Start terminal
Run preset commands   ← Launch tools/agents

When to use setup scripts vs presets:

Use Setup Scripts For	Use Presets For
Copying `.env` files	Launching agents
Installing dependencies	Starting dev servers
Running migrations	Opening terminals
Building assets	Running tests
One-time initialization	Repeated tasks

Setup scripts configure the workspace. Presets launch tools in the workspace.

Security Considerations

Setup and teardown scripts run with your user permissions. Be careful with:

Scripts from untrusted sources
Commands that modify files outside the workspace
Scripts that access sensitive data

Safe Practices

Review scripts before running: Check .superset/ contents in new projects
Limit scope: Only modify files within the workspace
Avoid sudo: Setup scripts shouldn’t require elevated permissions
Validate inputs: Don’t trust environment variables blindly

#!/usr/bin/env bash
set -euo pipefail

# Validate environment variables
if [ -z "${SUPERSET_WORKSPACE_NAME:-}" ]; then
  echo "Error: SUPERSET_WORKSPACE_NAME not set"
  exit 1
fi

if [ -z "${SUPERSET_ROOT_PATH:-}" ]; then
  echo "Error: SUPERSET_ROOT_PATH not set"
  exit 1
fi

# Your script logic...

Advanced Use Cases

Conditional Logic Based on Branch

#!/usr/bin/env bash
set -euo pipefail

# Get current branch name
BRANCH=$(git branch --show-current)

if [[ "$BRANCH" == feature/* ]]; then
  echo "Feature branch: using dev environment"
  cp "$SUPERSET_ROOT_PATH/.env.dev" .env
elif [[ "$BRANCH" == hotfix/* ]]; then
  echo "Hotfix branch: using production environment"
  cp "$SUPERSET_ROOT_PATH/.env.prod" .env
fi

Port Allocation

#!/usr/bin/env bash
set -euo pipefail

# Allocate unique port based on workspace name hash
PORT_BASE=$((8000 + $(echo "$SUPERSET_WORKSPACE_NAME" | md5sum | cut -c1-4 | sed 's/^0*//' || echo 0)))

echo "Allocated ports: $PORT_BASE - $((PORT_BASE + 10))"
echo "API_PORT=$PORT_BASE" >> .env
echo "WEB_PORT=$((PORT_BASE + 1))" >> .env

Caching Dependencies

#!/usr/bin/env bash
set -euo pipefail

CACHE_DIR="$SUPERSET_ROOT_PATH/.superset-cache/node_modules"

if [ -d "$CACHE_DIR" ]; then
  echo "Copying cached node_modules..."
  cp -R "$CACHE_DIR" node_modules
  bun install  # Update to latest
else
  echo "Installing dependencies from scratch..."
  bun install
  echo "Caching node_modules for future workspaces..."
  mkdir -p "$(dirname "$CACHE_DIR")"
  cp -R node_modules "$CACHE_DIR"
fi

Next Steps

Presets

Configure workspace presets that run after setup

Workspaces

Learn more about workspace creation

Quickstart

Create your first workspace with setup scripts

Worktrees

Understand git worktree mechanics

Get Started

Core Concepts

Guides

Resources

​Overview

​.superset/config.json Format

​Setup Scripts

​When Setup Scripts Run

​Example Setup Script

​Common Setup Tasks

Copy .env Files

Install Dependencies

Database Migrations

Build Assets

​Teardown Scripts

​When Teardown Scripts Run

​Example Teardown Script

​Common Teardown Tasks

Stop Services

Clean Temp Files

Archive Data

Cleanup Docker

​Environment Variables in Scripts

​Using Environment Variables

​Real Configuration Examples

​Example 1: Node.js Project

​Example 2: Python Project with Database

​Example 3: Docker Compose Project

​Example 4: Monorepo with Selective Install

​Example 5: Multi-Stage Setup

​Script Best Practices

Use set -euo pipefail

Provide Feedback

Handle Failures Gracefully

Make Scripts Idempotent

​Error Handling

​Performance Optimization

​Debugging Scripts

​1. Check Script Output

​2. Run Scripts Manually

​3. Add Debug Output

​4. Check Permissions

​Configuration Validation

​Relationship with Presets

​Security Considerations

​Safe Practices

​Advanced Use Cases

​Conditional Logic Based on Branch

​Port Allocation

​Caching Dependencies

​Next Steps

Presets

Workspaces

Quickstart

Worktrees

Build docs developers (and LLMs) love

Overview

.superset/config.json Format

Setup Scripts

When Setup Scripts Run

Example Setup Script

Common Setup Tasks

Teardown Scripts

When Teardown Scripts Run

Example Teardown Script

Common Teardown Tasks

Environment Variables in Scripts

Using Environment Variables

Real Configuration Examples

Example 1: Node.js Project

Example 2: Python Project with Database

Example 3: Docker Compose Project

Example 4: Monorepo with Selective Install

Example 5: Multi-Stage Setup

Script Best Practices

Error Handling

Performance Optimization

Debugging Scripts

1. Check Script Output

2. Run Scripts Manually

3. Add Debug Output

4. Check Permissions

Configuration Validation

Relationship with Presets

Security Considerations

Safe Practices

Advanced Use Cases

Conditional Logic Based on Branch

Port Allocation

Caching Dependencies

Next Steps