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, mirroring the repo's absolute path:

~/.superset/projects/<repo-path>/config.json

For a repo at /Users/me/work/app, that's ~/.superset/projects/Users/me/work/app/config.json. The legacy location keyed by project ID (~/.superset/projects/<project-id>/config.json) still works as a fallback.

Priority Order

For each key (setup, teardown, run), the highest-priority source that defines it wins:

1. ~/.superset/projects/<repo-path>/config.json: user override
2. <worktree>/.superset/config.json: workspace-specific (setup and teardown only)
3. <repo>/.superset/config.json: project default

Levels merge per key: a key one level doesn't define falls through to the next. run resolves at the project level, so it skips the worktree layer.

Script Fallback

If no commands are configured for a key, Superset looks for a script instead: .superset/<key>.sh (setup.sh, teardown.sh, run.sh) in the worktree first, then the main repo. A gitignored script isn't checked out into new worktrees, so it typically exists only in the main repo.

Working Directory

Set cwd to run commands somewhere other than the workspace root. Relative paths resolve against the worktree:

{ "cwd": "apps/web", "run": ["bun dev"] }

Examples

Custom setup script:

{
  "setup": ["~/.superset/projects/<repo-path>/setup.sh"],
  "teardown": ["~/.superset/projects/<repo-path>/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: it runs on 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