Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt

Use this file to discover all available pages before exploring further.

Every time Agentastic creates a new worktree for an agent, you can run a setup script to bring that worktree to a working state automatically. Use setup scripts to install dependencies, copy environment files, run database migrations, or perform any other initialization your project needs. This page covers both the worktree setup script (per-repository) and the container setup script (per-machine).

​
Worktree setup script

The worktree setup script runs inside each new worktree directory immediately after Agentastic creates it. It is defined per repository, so different projects can have different setup routines.

​
Location and permissions

Create the script in your repository at: 
.agentastic/setup.sh
Make it executable before committing: 
chmod +x .agentastic/setup.sh

​
Environment variables

Agentastic injects the following variables into your script at runtime:
VariableDescriptionExample
AGENTASTIC_BRANCHNew branch namefeature-auth
AGENTASTIC_BASE_BRANCHBase branch, if specifiedmain
AGENTASTIC_WORKTREE_PATHAbsolute path to the new worktree/Users/dev/repo-worktrees/feature-auth
AGENTASTIC_MAIN_REPO_PATHAbsolute path to the main repository/Users/dev/repo
AGENTASTIC_COMMITCommit SHA the worktree is based onabc123def456...
AGENTASTIC_REPO_NAMERepository folder namemy-project

​
Basic example

#!/bin/bash
set -euo pipefail

echo "Setting up worktree: $AGENTASTIC_BRANCH"

# Install dependencies
npm install

# Copy environment file from the main repo if it exists
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!"

​
Advanced example

This script detects the package manager, copies all .env files, and handles Ruby, Python, and Rails projects in addition to Node.js: 
#!/bin/bash
set -euo pipefail

echo "=== Agentastic Worktree Setup ==="
echo "Branch: $AGENTASTIC_BRANCH"
echo "Path: $AGENTASTIC_WORKTREE_PATH"

# Copy all .env files from main repo, preserving directory structure
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_env_files "$AGENTASTIC_MAIN_REPO_PATH" "$AGENTASTIC_WORKTREE_PATH"

# Detect package manager and install Node dependencies
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

# Rails database
if [ -f "bin/rails" ]; then
  echo "Setting up database..."
  bin/rails db:setup || bin/rails db:migrate
fi

echo "=== Setup complete ==="

​
Behavior notes

  • The script runs from the new worktree directory as its working directory.
  • Execution is non-blocking — worktree creation succeeds even if the script exits with an error.
  • Script output appears in the Worktree Setup task panel.
  • You can re-run the setup script at any time from the task panel.

​
Container setup script

The container setup script runs on your host machine before Agentastic creates a container. Instead of performing setup actions directly, it outputs a JSON object that Agentastic uses to configure the container.

​
Location

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

​
How it works

1

Agentastic runs your script

Agentastic executes the script with environment variables describing the worktree being containerized.
2

Your script prints JSON to stdout

The JSON object tells Agentastic which paths to mount, which environment variables to inject, and how to configure the container.
3

Agentastic parses the JSON and creates the container

The container is created with the mounts, environment variables, network mode, and shell you specified.

​
Output format

Your script must print a JSON object to stdout with the following structure: 
{
  "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 the first time you use containers. To open it for editing: 
open ~/.config/agentastic/container-setup.sh

​
Example customization

Add a shared npm cache mount and a custom environment variable to the default script: 
#!/bin/bash
# ... (default script content) ...

# Add a custom mount for npm cache
MOUNTS+='{"host": "'"$HOME"'/.npm", "container": "/root/.npm", "readonly": false},'

# Add a custom environment variable
ENV+='  "MY_CUSTOM_VAR": "my-value",'

# ... (rest of default script) ...

​
Environment variables

Agentastic passes these variables to the container setup script:
VariableDescription
AGENTASTIC_WORKTREE_PATHPath to the worktree being containerized
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 the container setup script

If your container setup script produces invalid output or you want to start fresh:
  1. Open Settings > Agents
  2. Click Reset Setup Script

​
Teardown scripts

Agentastic does not currently run teardown scripts automatically. To clean up a worktree when you are done:
  1. Stop any running processes in the worktree
  2. Remove the worktree via Settings > Agents or by running git worktree remove <path>
  3. Containers are stopped and removed automatically when you close the associated worktree

​
Best practices

​
Write idempotent scripts

Your script may be run more than once — for example, if you trigger it manually from the task panel. Make each step safe to repeat: 
# Good: only copies if the file is missing
[ -f .env ] || cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env

# Avoid: always overwrites, which can cause problems
cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env

​
Handle errors gracefully

Use set -euo pipefail to catch errors early, or handle individual failures explicitly: 
set -euo pipefail

# Or, allow specific steps to fail without stopping the whole script
npm install || echo "npm install failed, continuing..."

​
Log progress

Print messages at each stage so you can follow along in the task panel: 
echo "Step 1: Installing dependencies..."
npm install

echo "Step 2: Copying environment files..."
# ...

​
Test your script manually

Before committing, run the script yourself with the expected environment variables to catch any issues: 
AGENTASTIC_BRANCH=test \
AGENTASTIC_WORKTREE_PATH=/tmp/test \
AGENTASTIC_MAIN_REPO_PATH=/path/to/repo \
.agentastic/setup.sh

​
Troubleshooting

Check three things:
  1. The file exists at .agentastic/setup.sh
  2. It is executable: chmod +x .agentastic/setup.sh
  3. It has no syntax errors: bash -n .agentastic/setup.sh
Add shell debugging flags at the top of your script:
set -x  # Print each command as it runs
set -e  # Exit immediately on any error
The output appears in the Worktree Setup task panel.
Print them at the start of your script to verify they are being injected:
echo "AGENTASTIC_BRANCH: $AGENTASTIC_BRANCH"
echo "AGENTASTIC_WORKTREE_PATH: $AGENTASTIC_WORKTREE_PATH"
Test the script directly and pipe its output through jq to find syntax errors:
~/.config/agentastic/container-setup.sh | jq .
If jq reports a parse error, fix the JSON syntax in your script and test again.