Setup & Teardown Scripts
Automate worktree and container initialization with setup, teardown, and archive scripts, copy ignored files, and give each worktree its own ports.
On this page
- Overview
- Worktree Setup Script
- Location
- Basic Example
- Environment Variables
- Advanced Example
- Behavior
- Choose Scripts with config.json
- Copy Ignored Files
- Ports and Compatibility Variables
- Container Setup Script
- Location
- How It Works
- Output Format
- Default Script
- Example Customization
- Environment Variables
- Resetting
- Teardown Scripts
- Archive Scripts
- Best Practices
- Keep Scripts Idempotent
- Handle Errors Gracefully
- Log Progress
- Test Manually
- Troubleshooting
- Script Not Running
- Script Fails Silently
- Environment Variables Missing
- Container Setup Invalid JSON
Overview#
Agentastic runs your repository's scripts at three points in a workspace's life:
| Script | Runs | Default |
|---|---|---|
| Setup | After a new worktree or container is created | .agentastic/setup.sh |
| Teardown | Before Agentastic deletes a local worktree | .agentastic/teardown.sh |
| Archive | Before Agentastic archives a workspace | None; 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.shMake it executable:
chmod +x .agentastic/setup.shBasic Example#
#!/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:
| Variable | Description | Example |
|---|---|---|
AGENTASTIC_BRANCH | New branch name | feature-auth |
AGENTASTIC_BASE_BRANCH | Base branch (if specified) | main |
AGENTASTIC_WORKTREE_PATH | Path to new worktree | /Users/dev/repo-worktrees/feature-auth |
AGENTASTIC_MAIN_REPO_PATH | Path to main repository | /Users/dev/repo |
AGENTASTIC_COMMIT | Commit SHA | abc123def456... |
AGENTASTIC_REPO_NAME | Repository folder name | my-project |
AGENTASTIC_PORT | First 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#
#!/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:
{
"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
setuporteardownis missing, the default path is used. An empty list ([]) turns that phase off. archivehas no default. When a worktree's ownconfig.jsonhas noarchivekey, 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:
# .worktreeinclude
.env
.env.local
config/*.local.yml
!config/secrets.local.ymlPatterns 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:
| Variable | Value |
|---|---|
CONDUCTOR_PORT, SUPERSET_PORT, SUPERSET_PORT_BASE | Same as AGENTASTIC_PORT |
CONDUCTOR_ROOT_PATH, SUPERSET_ROOT_PATH | Main repository path |
CONDUCTOR_WORKSPACE_PATH, CONDUCTOR_WORKSPACE_ID, SUPERSET_WORKSPACE_PATH | Worktree path |
CONDUCTOR_WORKSPACE_NAME, SUPERSET_WORKSPACE_NAME | Worktree folder name |
CONDUCTOR_DEFAULT_BRANCH | Repository's default branch |
SUPERSET_BRANCH_NAME | Worktree branch |
CONDUCTOR_IS_LOCAL | 1 |
SUPERSET_ENV | local |
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.
# 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.shHow It Works#
- Agentastic runs your script with environment variables
- Script outputs JSON to stdout
- Agentastic parses JSON to configure the container
Output Format#
{
"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:
open ~/.config/agentastic/container-setup.shExample Customization#
Add a shared npm cache:
#!/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#
| Variable | Description |
|---|---|
AGENTASTIC_WORKTREE_PATH | Path to the worktree |
AGENTASTIC_REPO_NAME | Repository name |
AGENTASTIC_BRANCH | Branch name |
AGENTASTIC_MOUNT_SSH_KEYS | true or false |
AGENTASTIC_MOUNT_GIT_CONFIG | true or false |
AGENTASTIC_COPY_SHELL_CONFIG | true or false |
AGENTASTIC_NETWORK_MODE | bridge, restricted, or none |
Resetting#
If your script has issues:
- Open Settings > Containers
- 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:
- The
archivelist in the worktree's.agentastic/config.json - The
archivelist in the main checkout's.agentastic/config.json - 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:
# Good: only copy if missing
[ -f .env ] || cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env
# Avoid: always overwrites
cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .envHandle Errors Gracefully#
set -euo pipefail # Exit on errors
# Or handle specific failures
npm install || echo "npm install failed, continuing..."Log Progress#
echo "Step 1: Installing dependencies..."
npm install
echo "Step 2: Copying environment files..."
# ...Test Manually#
Run your script manually to debug:
AGENTASTIC_BRANCH=test \
AGENTASTIC_WORKTREE_PATH=/tmp/test \
AGENTASTIC_MAIN_REPO_PATH=/path/to/repo \
.agentastic/setup.shTroubleshooting#
Script Not Running#
- Check script exists at
.agentastic/setup.sh - Verify it's executable:
chmod +x .agentastic/setup.sh - Check for syntax errors:
bash -n .agentastic/setup.sh
Script Fails Silently#
Add debugging:
set -x # Print each command
set -e # Exit on errorEnvironment Variables Missing#
Print them to verify:
echo "AGENTASTIC_BRANCH: $AGENTASTIC_BRANCH"
echo "AGENTASTIC_WORKTREE_PATH: $AGENTASTIC_WORKTREE_PATH"Container Setup Invalid JSON#
Test your script:
~/.config/agentastic/container-setup.sh | jq .If jq reports an error, fix the JSON syntax in your script.