Setup & Teardown Scripts

Automate worktree and container initialization with setup, teardown, and archive scripts, copy ignored files, and give each worktree its own ports.

View as Markdown

Overview#

Agentastic runs your repository's scripts at three points in a workspace's life:

ScriptRunsDefault
SetupAfter a new worktree or container is created.agentastic/setup.sh
TeardownBefore Agentastic deletes a local worktree.agentastic/teardown.sh
ArchiveBefore Agentastic archives a workspaceNone; set it in .agentastic/config.json or Settings > Workspaces

Use setup scripts to:

  • Install dependencies (npm install, bundle install)
  • Copy environment files (.env, .envrc)
  • Run database migrations
  • Configure project-specific settings

Ignored files such as .env can also be copied without a script; see Copy ignored files. Coming from Conductor, Superset, or Codex? Import from Other Apps can translate their scripts for you.

Worktree Setup Script#

Location#

Create a setup script in your repository:

.agentastic/setup.sh

Make it executable:

bash
chmod +x .agentastic/setup.sh

Basic Example#

bash
#!/bin/bash set -euo pipefail echo "Setting up worktree: $AGENTASTIC_BRANCH" # Install dependencies npm install # Copy environment file if [ -f "$AGENTASTIC_MAIN_REPO_PATH/.env" ]; then cp "$AGENTASTIC_MAIN_REPO_PATH/.env" "$AGENTASTIC_WORKTREE_PATH/.env" echo "Copied .env file" fi echo "Setup complete!"

Environment Variables#

Your script receives these variables:

VariableDescriptionExample
AGENTASTIC_BRANCHNew branch namefeature-auth
AGENTASTIC_BASE_BRANCHBase branch (if specified)main
AGENTASTIC_WORKTREE_PATHPath to new worktree/Users/dev/repo-worktrees/feature-auth
AGENTASTIC_MAIN_REPO_PATHPath to main repository/Users/dev/repo
AGENTASTIC_COMMITCommit SHAabc123def456...
AGENTASTIC_REPO_NAMERepository folder namemy-project
AGENTASTIC_PORTFirst of ten ports set aside for this worktree (local worktrees only)24310

See Ports and compatibility variables for AGENTASTIC_PORT and the Conductor and Superset names that scripts from those apps expect.

Advanced Example#

bash
#!/bin/bash set -euo pipefail echo "=== Agentastic Worktree Setup ===" echo "Branch: $AGENTASTIC_BRANCH" echo "Path: $AGENTASTIC_WORKTREE_PATH" # Function to copy env files copy_env_files() { local source="$1" local dest="$2" find "$source" -name '.env*' -type f | while read -r file; do relative="${file#$source/}" target="$dest/$relative" mkdir -p "$(dirname "$target")" cp "$file" "$target" echo "Copied: $relative" done } # Copy all .env files from main repo copy_env_files "$AGENTASTIC_MAIN_REPO_PATH" "$AGENTASTIC_WORKTREE_PATH" # Detect package manager and install if [ -f "package-lock.json" ]; then echo "Installing with npm..." npm ci elif [ -f "yarn.lock" ]; then echo "Installing with yarn..." yarn install --frozen-lockfile elif [ -f "pnpm-lock.yaml" ]; then echo "Installing with pnpm..." pnpm install --frozen-lockfile fi # Ruby/Rails if [ -f "Gemfile" ]; then echo "Installing Ruby gems..." bundle install fi # Python if [ -f "requirements.txt" ]; then echo "Setting up Python environment..." python -m venv .venv .venv/bin/pip install -r requirements.txt fi # Run database setup if Rails if [ -f "bin/rails" ]; then echo "Setting up database..." bin/rails db:setup || bin/rails db:migrate fi echo "=== Setup complete ==="

Behavior#

  • Script runs from the new worktree directory
  • Script execution is non-blocking - worktree creation succeeds even if script fails
  • Output appears in the "Worktree Setup" task panel
  • You can re-run the setup script from the task panel

Choose Scripts with config.json#

To use other script paths, or several scripts per phase, add .agentastic/config.json:

json
{ "setup": [".agentastic/setup.sh", "scripts/seed-db.sh"], "teardown": [".agentastic/teardown.sh"], "archive": [".agentastic/archive.sh"] }
  • Paths are relative to the worktree root, and each script must be executable.
  • Scripts in a list run in order.
  • If setup or teardown is missing, the default path is used. An empty list ([]) turns that phase off.
  • archive has no default. When a worktree's own config.json has no archive key, the main checkout's is used.

Agentastic reads the file from the worktree, so commit it with your scripts.

Copy Ignored Files#

A new worktree contains only tracked files. To bring Git-ignored files such as .env along, list them in a .worktreeinclude file at the root of the main checkout:

gitignore
# .worktreeinclude .env .env.local config/*.local.yml !config/secrets.local.yml

Patterns follow .gitignore rules: # comments, ! exclusions (the last match wins), a leading / to anchor at the root, a trailing / for directories, and *, ?, and **. Only files that Git reports as ignored and untracked in the main checkout are copied. Claude Code, Codex, and Orca read the same file, so an existing .worktreeinclude works as is.

You can also list paths under Settings > Workspaces > Files to copy; that setting applies to every repository.

On creation, Agentastic copies .worktreeinclude matches first, then Files to copy, then runs the setup script.

Ports and Compatibility Variables#

Each local worktree other than the main checkout gets its own block of ten ports. AGENTASTIC_PORT is the first port in the block, so a worktree can use $AGENTASTIC_PORT through $AGENTASTIC_PORT + 9. The block is chosen between 10000 and 59999 and stays the same across launches, and no two worktrees share one. Agentastic only assigns numbers: it doesn't check that a port is free or keep other apps off it.

The same block is exposed under the names Conductor and Superset scripts expect, so scripts from those apps can run unchanged:

VariableValue
CONDUCTOR_PORT, SUPERSET_PORT, SUPERSET_PORT_BASESame as AGENTASTIC_PORT
CONDUCTOR_ROOT_PATH, SUPERSET_ROOT_PATHMain repository path
CONDUCTOR_WORKSPACE_PATH, CONDUCTOR_WORKSPACE_ID, SUPERSET_WORKSPACE_PATHWorktree path
CONDUCTOR_WORKSPACE_NAME, SUPERSET_WORKSPACE_NAMEWorktree folder name
CONDUCTOR_DEFAULT_BRANCHRepository's default branch
SUPERSET_BRANCH_NAMEWorktree branch
CONDUCTOR_IS_LOCAL1
SUPERSET_ENVlocal

These variables reach setup, teardown, and archive scripts, terminals in those worktrees, and run tasks created by an import. Container, cloud, and remote workspaces don't get them.

bash
# Start a dev server on this worktree's first port npm run dev -- --port "$AGENTASTIC_PORT"

Container Setup Script#

Container setup scripts run on your host machine before the container is created. They output JSON configuration.

Location#

~/.config/agentastic/container-setup.sh

How It Works#

  1. Agentastic runs your script with environment variables
  2. Script outputs JSON to stdout
  3. Agentastic parses JSON to configure the container

Output Format#

json
{ "mounts": [ {"host": "/path/on/host", "container": "/path/in/container", "readonly": true} ], "env": { "ANTHROPIC_API_KEY": "sk-...", "CUSTOM_VAR": "value" }, "network": "bridge", "workdir": "/workspace", "shell": "/bin/bash" }

Default Script#

Agentastic creates a default script if none exists. To customize:

bash
open ~/.config/agentastic/container-setup.sh

Example Customization#

Add a shared npm cache:

bash
#!/bin/bash # ... (default script content) ... # Add custom mount for npm cache MOUNTS+='{"host": "'"$HOME"'/.npm", "container": "/root/.npm", "readonly": false},' # Add custom environment variable ENV+=' "MY_CUSTOM_VAR": "my-value",' # ... (rest of default script) ...

Environment Variables#

VariableDescription
AGENTASTIC_WORKTREE_PATHPath to the worktree
AGENTASTIC_REPO_NAMERepository name
AGENTASTIC_BRANCHBranch name
AGENTASTIC_MOUNT_SSH_KEYStrue or false
AGENTASTIC_MOUNT_GIT_CONFIGtrue or false
AGENTASTIC_COPY_SHELL_CONFIGtrue or false
AGENTASTIC_NETWORK_MODEbridge, restricted, or none

Resetting#

If your script has issues:

  1. Open Settings > Containers
  2. Click Reset next to Setup script

Teardown Scripts#

Agentastic's local worktree deletion path runs executable teardown scripts before removing the worktree. The default is .agentastic/teardown.sh; .agentastic/config.json can configure a different list. Scripts run in the worktree and receive AGENTASTIC_WORKTREE_PATH, AGENTASTIC_MAIN_REPO_PATH, AGENTASTIC_REPO_NAME, and the branch when available.

Make the script executable and keep cleanup repeatable. Failures are non-fatal and do not prevent deletion, so confirm external services were removed. Stop foreground servers before removing their checkout. Container-backed deletion also removes the associated container.

A direct git worktree remove does not invoke Agentastic scripts. Run any required project cleanup yourself before using it.

Archive Scripts#

Archiving hides a workspace but keeps its checkout, so it runs a separate script from teardown. Use it to stop services or free resources that a parked workspace shouldn't hold.

Agentastic looks for an archive script in this order:

  1. The archive list in the worktree's .agentastic/config.json
  2. The archive list in the main checkout's .agentastic/config.json
  3. Settings > Workspaces > Archive script, an absolute path or one relative to the workspace root

The script runs with Bash in the worktree, receives the same variables as teardown, and must be executable. If it exits with a non-zero status, the workspace stays unarchived: fix the script, or remove it from the configuration, and archive again. Agentastic stops the workspace's terminals only after the script succeeds.

For a complete environment and preview workflow, see worktree setup, ports, and browser previews.

Best Practices#

Keep Scripts Idempotent#

Scripts should be safe to run multiple times:

bash
# Good: only copy if missing [ -f .env ] || cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env # Avoid: always overwrites cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env

Handle Errors Gracefully#

bash
set -euo pipefail # Exit on errors # Or handle specific failures npm install || echo "npm install failed, continuing..."

Log Progress#

bash
echo "Step 1: Installing dependencies..." npm install echo "Step 2: Copying environment files..." # ...

Test Manually#

Run your script manually to debug:

bash
AGENTASTIC_BRANCH=test \ AGENTASTIC_WORKTREE_PATH=/tmp/test \ AGENTASTIC_MAIN_REPO_PATH=/path/to/repo \ .agentastic/setup.sh

Troubleshooting#

Script Not Running#

  1. Check script exists at .agentastic/setup.sh
  2. Verify it's executable: chmod +x .agentastic/setup.sh
  3. Check for syntax errors: bash -n .agentastic/setup.sh

Script Fails Silently#

Add debugging:

bash
set -x # Print each command set -e # Exit on error

Environment Variables Missing#

Print them to verify:

bash
echo "AGENTASTIC_BRANCH: $AGENTASTIC_BRANCH" echo "AGENTASTIC_WORKTREE_PATH: $AGENTASTIC_WORKTREE_PATH"

Container Setup Invalid JSON#

Test your script:

bash
~/.config/agentastic/container-setup.sh | jq .

If jq reports an error, fix the JSON syntax in your script.