Setup Script

Setup Script allows you to define commands that automatically run after your repository is cloned into the sandbox. This is useful for installing dependencies, setting up databases, or any other initialization tasks.

Overview

When Claude starts working on your task, the following happens:

Your repository is cloned into the sandbox
Setup Script runs automatically (if configured)
Claude begins working on your task

This ensures your development environment is ready before any actual work begins.

How to Configure

You can configure a Setup Script for each repository:

Go to Environments page
Find the repository you want to configure
Click on the repository settings
Find the Setup Script section
Enter your setup commands
Save changes

Script Format

The setup script is executed as a bash script. You can include multiple commands:

# Install Node.js dependencies
bun install

# Run database migrations
bun run db:migrate

# Build the project
bun run build

Each command runs sequentially. If a command fails, subsequent commands will still attempt to run.

Common Use Cases

Node.js Projects

# Using Bun
bun install

# Using pnpm
pnpm install

# Using Yarn
yarn install

PHP Projects

# Install Composer dependencies
composer install

# Copy environment file
cp .env.example .env

# Generate application key (Laravel)
php artisan key:generate

Rust Projects

# Build the project
cargo build

# Or just fetch dependencies
cargo fetch

Go Projects

# Download dependencies
go mod download

# Build the project
go build ./...

Python Projects

# Using uv (recommended)
uv pip install -r requirements.txt

# Or create virtual environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Monorepo Projects

# Install root dependencies
bun install

# Install workspace dependencies
bun install --frozen-lockfile

# Build shared packages
bun run build:packages

Environment Variables

Setup scripts have access to environment variables you've configured. See Environments for more details.

# Access environment variables in your script
echo $DATABASE_URL
bun run db:migrate

Best Practices

Keep It Fast

Setup scripts run before every task. Keep them as fast as possible:

# Good: Only install if needed
[ ! -d "node_modules" ] && bun install

# Good: Use frozen lockfile for faster installs
bun install --frozen-lockfile

Handle Errors Gracefully

# Continue even if a command fails
bun install || true

# Or check if command exists
command -v composer && composer install

Use Caching When Possible

Some package managers support caching:

# pnpm with cache
pnpm install --frozen-lockfile

# Cargo (dependencies are cached)
cargo fetch

Debugging Setup Scripts

If your setup script isn't working as expected:

Check the task logs for error messages
Make sure all commands are valid bash syntax
Verify that required tools are available in the sandbox
Test commands locally first

Setup scripts run in the sandbox environment. Make sure all tools you use are either pre-installed or installed by the script itself.

Examples by Project Type

Next.js Application

bun install
cp .env.example .env.local
bun run build

Laravel Application

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force

Full-Stack Monorepo

# Install dependencies
bun install

# Setup backend
cd backend && composer install && cd ..

# Setup frontend
cd frontend && bun install && cd ..

# Build shared types
bun run build:types

Setup Script

On this page