Setup Scripts

Setup scripts are bash scripts that run automatically when a workspace starts. They let you define reproducible environments - install packages, clone repos, seed databases, configure tools - so every workspace boots into a ready-to-use state.

How Setup Scripts Work

When a workspace starts, Rigbox executes all attached setup scripts inside the VM as the developer user. Scripts run sequentially in the order you specify, with full network access and sudo privileges. Each script has a run mode that controls when it executes:

Run Mode	Behavior
`first_boot`	Runs only once, on the very first start of the workspace
`every_start`	Runs on every workspace start (including restarts and resumes)

Use first_boot for one-time setup like installing packages or cloning repos. Use every_start for configuration that might change between restarts, like refreshing tokens or syncing files.

Create a Setup Script

Write the script to a local file, then create it with the CLI. Once created, you can attach it to any number of workspaces.

cat > python-data-stack.sh <<'EOF'
#!/bin/bash
set -e
pip install pandas numpy scikit-learn matplotlib
echo "Data stack installed successfully"
EOF

rig setup-script create --name python-data-stack --file python-data-stack.sh

See the Setup Scripts API reference for the full request and response schema.

Script Content Guidelines

Setup scripts run as bash inside the workspace VM. Here are guidelines for writing reliable scripts:

#!/bin/bash
set -e  # Exit on first error

# Use absolute paths - the working directory is /home/developer
PROJECT_DIR="/home/developer/my-project"

# Install system packages (sudo is available)
sudo apt-get update -qq
sudo apt-get install -y -qq postgresql-client redis-tools

# Install language-specific packages
pip install -q flask sqlalchemy celery

# Clone repositories
git clone https://github.com/your-org/your-repo.git "$PROJECT_DIR"
cd "$PROJECT_DIR" && pip install -r requirements.txt

# Seed data or run migrations
cd "$PROJECT_DIR" && python manage.py migrate

echo "Setup complete!"

Always use set -e at the top of your scripts. Without it, a failing command will not stop execution, and subsequent commands may run in a broken state.

Attach Scripts to a Workspace

Pass --setup-script-id (repeatable) when spawning a workspace. Scripts run in the order you list them.

rig workspace spawn --name ml-workspace --template dev \
  --setup-script-id ss_abc123 \
  --setup-script-id ss_def456

Script Ordering

Scripts execute sequentially in array order. This is important when scripts have dependencies:

{
  "setup_script_ids": [
    "ss_system_deps",    // 1. Install system packages
    "ss_clone_repo",     // 2. Clone the repo (needs git from step 1)
    "ss_python_deps",    // 3. Install Python deps (needs repo from step 2)
    "ss_seed_data"       // 4. Seed database (needs packages from step 3)
  ]
}

List Your Scripts

Retrieve all setup scripts in your account.

rig setup-script ls

[
  {
    "id": "ss_abc123",
    "name": "python-data-stack",
    "run_on": "first_boot",
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-01T10:00:00Z"
  },
  {
    "id": "ss_def456",
    "name": "git-config",
    "run_on": "every_start",
    "created_at": "2026-04-02T14:30:00Z",
    "updated_at": "2026-04-02T14:30:00Z"
  }
]

See the List Setup Scripts API reference for pagination and filtering options.

Update a Script

Modify an existing script’s name and/or body. Pass --name, --file, or both.

cat > python-data-stack.sh <<'EOF'
#!/bin/bash
set -e
pip install pandas numpy scikit-learn matplotlib seaborn
echo "Data stack v2 installed"
EOF

rig setup-script update --id ss_abc123 \
  --name python-data-stack-v2 \
  --file python-data-stack.sh

Updating a script affects all future workspace starts that reference it. Already-running workspaces will pick up the change on their next restart (for every_start scripts) or not at all (for first_boot scripts that have already executed).

Delete a Script

rig setup-script rm --id ss_abc123

Deleting a script that is still attached to workspaces will cause those workspaces to skip that script on future starts. The workspace itself is not affected.

Combining with Templates

Templates can include their own setup scripts. When you create a workspace with both a template and additional setup_script_ids, the template’s scripts run first, followed by yours.

{
  "name": "custom-workspace",
  "template_id": "dev",
  "setup_script_ids": ["ss_my_custom_config"]
}

Execution order:

Template dev scripts (e.g., install Node.js, npm packages)
Your script ss_my_custom_config (e.g., clone your repo, set up environment)

This layering lets you build on top of standard templates without duplicating their setup logic.

Use Case: Team Onboarding

Create a single setup script that configures everything a new team member needs. Every workspace they create starts fully configured.

#!/bin/bash
set -e

# Configure git
git config --global user.name "$GIT_USER_NAME"
git config --global user.email "$GIT_USER_EMAIL"
git config --global pull.rebase true

# Clone the monorepo
git clone https://github.com/acme-corp/platform.git /home/developer/platform

# Install dependencies
cd /home/developer/platform
npm ci

# Set up local database
cd /home/developer/platform
npm run db:migrate
npm run db:seed

# Install team CLI tools
npm install -g @acme/cli turbo

echo "Welcome to the Acme Platform team workspace!"

Then set this as the default for all new workspaces via a template, and every new hire gets an identical development environment in seconds.

Use Case: Ephemeral Demo Environments

For product demos, create a setup script that loads sample data and starts services:

#!/bin/bash
set -e

# Clone the demo branch
git clone -b demo https://github.com/acme-corp/product.git /home/developer/demo
cd /home/developer/demo

# Install and seed
npm ci
npm run db:setup -- --demo-data

# Generate sample reports
node scripts/generate-reports.js

echo "Demo environment ready"

Combine this with a service spec that auto-starts the app server, and you have a one-click demo environment.

Debugging Setup Scripts

If a setup script fails, the workspace will still start, but the script’s exit code and output are captured. To check script execution results, look at the workspace status after it starts:

rig api GET /v1/workspaces/{workspace_id} --query setup_status

Add echo statements throughout your scripts for visibility. The output is captured and available in the workspace details, making it easier to pinpoint where a script failed.

Next Steps

Service Specs - define background services that auto-start after setup completes
Snapshots - snapshot a fully configured workspace and restore it later
Managed AI Proxy - add AI capabilities to your scripted environments

Getting Started

Concepts

Deploying & hosting

AI, automation & data

CLI Reference

Integrations & tools

Build on Rigbox

How Setup Scripts Work

Create a Setup Script

Script Content Guidelines

Attach Scripts to a Workspace

Script Ordering

List Your Scripts

Update a Script

Delete a Script

Combining with Templates

Use Case: Team Onboarding

Use Case: Ephemeral Demo Environments

Debugging Setup Scripts

Next Steps

​How Setup Scripts Work

​Create a Setup Script

​Script Content Guidelines

​Attach Scripts to a Workspace

​Script Ordering

​List Your Scripts

​Update a Script

​Delete a Script

​Combining with Templates

​Use Case: Team Onboarding

​Use Case: Ephemeral Demo Environments

​Debugging Setup Scripts

​Next Steps

How Setup Scripts Work

Create a Setup Script

Script Content Guidelines

Attach Scripts to a Workspace

Script Ordering

List Your Scripts

Update a Script

Delete a Script

Combining with Templates

Use Case: Team Onboarding

Use Case: Ephemeral Demo Environments

Debugging Setup Scripts

Next Steps