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.

Before you begin

Use the v0.13 CLI and authenticate. Run workspace-management and recipe commands from your local terminal. Commands identified as running inside a workspace require its console terminal or SSH session. Replace example resource IDs with the values returned for your account. Create, update, and delete setup scripts from your local terminal. Inside a workspace, rig setup-script ls works, but the commands that change a script refuse: an account script also runs in your other workspaces, so a workspace can’t change one.

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 the workspace’s 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. The CLI create command uses the API’s default first_boot run mode; use the Setup Scripts API when you need to explicitly choose every_start. Once created, attach its returned ID to the intended 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

Check which workspaces reference a script before deleting it. Removing the stored definition does not undo changes made by an earlier run.

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. Read workspace logs after startup; there is no setup_status field to query on the workspace response:

rig workspace logs --workspace WORKSPACE_ID

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.

Verify and troubleshoot

Use the returned definition ID when attaching it to a workspace. After startup, inspect rig workspace logs --workspace WORKSPACE_ID; for service specs, check the installed unit with the commands above. A running VM does not prove a setup script or application completed successfully. For failures, start with runtime logs, health checks, or resource exhaustion.

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

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Before you begin

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

Verify and troubleshoot

Next Steps

​Before you begin

​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

​Verify and troubleshoot

​Next Steps

Before you begin

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

Verify and troubleshoot

Next Steps