> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Scripts

> Automate workspace initialization with reusable bash 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) |

<Tip>
  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.
</Tip>

## 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.

```bash theme={null}
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](/api-reference/setup-scripts/create) 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:

```bash theme={null}
#!/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!"
```

<Warning>
  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.
</Warning>

## Attach Scripts to a Workspace

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

```bash theme={null}
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:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash CLI theme={null}
  rig setup-script ls
  ```

  ```json Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</CodeGroup>

See the [List Setup Scripts API reference](/api-reference/setup-scripts/list) for pagination and filtering options.

## Update a Script

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

```bash theme={null}
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
```

<Note>
  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).
</Note>

## Delete a Script

```bash theme={null}
rig setup-script rm --id ss_abc123
```

<Warning>
  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.
</Warning>

## 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.

```json theme={null}
{
  "name": "custom-workspace",
  "template_id": "dev",
  "setup_script_ids": ["ss_my_custom_config"]
}
```

Execution order:

1. Template `dev` scripts (e.g., install Node.js, npm packages)
2. 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.

```bash theme={null}
#!/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:

```bash theme={null}
#!/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](/guides/service-specs) 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:

```bash theme={null}
rig api GET /v1/workspaces/{workspace_id} --query setup_status
```

<Tip>
  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.
</Tip>

## Next Steps

* [Service Specs](/guides/service-specs) - define background services that auto-start after setup completes
* [Snapshots](/guides/snapshots) - snapshot a fully configured workspace and restore it later
* [Managed AI Proxy](/guides/managed-proxy) - add AI capabilities to your scripted environments