Setup Scripts

Automate runner initialization with .forkline/setup.sh and .forkline/setup.rh. Both run after git clone and before the AI agent starts.

Overview

Setup scripts are useful when a repository needs repeatable preparation before work begins:

• Install dependencies
• Configure the environment
• Set up local databases or services
• Run migrations
• Prepare tools and utilities

Info: Setup scripts live in your repository, so the setup process is version-controlled alongside the code it supports.

Execution order

01 Phase 01

Clone Repository

The runner checks out the repository root before any setup logic begins.

02 Phase 02

.forkline/setup.rh

Declarative Rash tasks run first when the file is present.

03 Phase 03

.forkline/setup.sh

Imperative Bash glue runs second when the file is present.

04 Phase 04

OpenCode Starts

The interactive agent session continues even if setup logged non-fatal errors.

Repository root working directory5 minute timeout per scriptFailures are logged, not fatal

Script Types

Script	Format	Best For
.forkline/setup.rh	Rash (YAML)	Declarative, idempotent setup
.forkline/setup.sh	Bash	Imperative commands and glue scripts

Bash Scripts (.forkline/setup.sh)

Basic Example

#!/bin/bash
set -euo pipefail

# Install dependencies
npm install

# Run database migrations
npm run db:migrate

# Seed test data
npm run db:seed

Using Secrets

Repository secrets are available as environment variables:

#!/bin/bash
set -euo pipefail

# Secrets are automatically available
echo "Setting up database..."
export DATABASE_URL="$DATABASE_URL"

# Run migrations
npm run db:migrate

# Configure API clients
export STRIPE_API_KEY="$STRIPE_API_KEY"

Warning: Setup script failures are non-fatal. The runner continues to start, but the environment may be incomplete. Check logs if the workspace behaves unexpectedly.

Rash Scripts (.forkline/setup.rh)

Rash is a declarative YAML-based shell language designed for container workflows.

Basic Example

#!/bin/rash
- name: Install dependencies
  command:
    argv: [npm, install]

- name: Run migrations
  command:
    argv: [npm, run, db:migrate]

- name: Create .env file
  copy:
    content: |
      DATABASE_URL={{ env.DATABASE_URL }}
      API_KEY={{ env.API_KEY }}
    dest: .env
    mode: "600"

Script Behavior

Property	Value
Working directory	Repository root
Environment	Secrets are injected as env vars
Timeout	5 minutes per script
Failure	Non-fatal, logged, runner continues

Next Steps

• Configure repository secrets
• Start a runner to test scripts
• Learn about Rash for advanced setups