Setup, Teardown & Run Scripts

Overview

Run commands automatically when creating or deleting workspaces, and define dev server commands that launch via the Run button.

Create .superset/config.json in your project:

{
  "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"],
  "teardown": ["docker-compose down"],
  "run": ["./.superset/run.sh"]
}

How It Works

1. Create workspace → setup commands run in a terminal
2. Delete workspace → teardown commands run
3. Click the Run button → run commands execute in a dedicated pane

Setup and teardown commands run sequentially in the workspace directory.

Run Script

The run field defines commands that start your dev server or other long-running processes. Unlike setup/teardown, run commands are:

• On-demand — triggered by the Run button, not automatically on workspace creation
• Restartable — stop and restart from the UI without recreating the workspace
• Dedicated pane — runs in its own terminal pane separate from your shell

{
  "setup": ["npm install"],
  "run": ["./.superset/run.sh"]
}

Environment Variables

Examples

Node.js:

{ "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] }

Docker:

{
  "setup": ["docker-compose up -d", "bun run db:migrate"],
  "teardown": ["docker-compose down -v"]
}

Full config:

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

User Overrides

Override project scripts without modifying the repo by placing a config.json in your home directory:

~/.superset/projects/<project-id>/config.json

Where <project-id> is your project's unique ID in Superset (visible in the app's project settings).

Priority Order

Config is resolved in this order (first found wins, for setup, teardown, and run):

1. ~/.superset/projects/<project-id>/config.json — user override
2. <worktree>/.superset/config.json — worktree-specific
3. <repo>/.superset/config.json — project default

No merging occurs between levels—the first config found is used entirely.

Examples

Custom setup script:

{
  "setup": ["~/.superset/projects/<project-id>/setup.sh"],
  "teardown": ["~/.superset/projects/<project-id>/teardown.sh"]
}

Skip setup entirely:

{ "setup": [], "teardown": [] }

Local Config

Extend or override your team's committed scripts without modifying the repo. Create .superset/config.local.json alongside config.json — it's gitignored automatically.

Prepend and/or append

Add steps before or after the team's scripts:

{
  "setup": {
    "before": ["echo 'running pre-setup'"],
    "after": ["./.superset/my-post-setup.sh"]
  },
  "teardown": {
    "after": ["./.superset/my-cleanup.sh"]
  }
}

Result: before → committed setup scripts → after. Keys you don't specify pass through unchanged.

Override entirely

Use a plain array to replace the team's scripts completely:

{
  "setup": ["./.superset/my-custom-setup.sh"]
}

Mix and match

Override one key while extending the other:

{
  "setup": { "after": ["bun run my-extra-step"] },
  "teardown": ["my-custom-teardown.sh"]
}

Resolution order

The local config merges on top of whichever base config wins the priority order. If a config.local.json exists in both the worktree and main repo, the worktree's local config takes priority.

Force Delete

If teardown scripts fail during workspace deletion, you can force-delete to skip the failed teardown and continue cleanup.

When teardown fails:

1. Error toast appears with "Delete Anyway" and "View Logs" buttons
2. Click "Delete Anyway" to force-delete immediately
3. Or click "View Logs" to review the failure, then force-delete from the dialog

Tips

• Keep setup fast—runs every workspace creation
• Commit .superset/ to share with team
• Use shell scripts for complex logic: "setup": ["./.superset/setup.sh"]
• Use config.local.json to add personal steps without touching the team's config
• Use user overrides (~/.superset/projects/) to replace scripts entirely per-project
• Use run for dev servers instead of putting them in setup—run scripts are restartable and don't block workspace creation