Documentation

Bootstrap

Automate new machine setup on first pull

Overview

The bootstrap script runs automatically the first time you pull to a new machine. Use it to install tools, clone repos, configure your shell, or anything else needed to set up a fresh environment.

i
The bootstrap script is synced alongside your configs — it is pushed with your state and available on every pull.

Getting Started

Place a script at ~/.configsync/bootstrap.sh and it will be included in your next push:

~/.configsync/bootstrap.sh

#!/bin/bash

set -e

# Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install packages from Brewfile

brew bundle install --file=~/.config/Brewfile --no-lock

# Clone repos

mkdir -p ~/git

git clone git@github.com:myorg/myapp.git ~/git/myapp

# Set default shell

chsh -s $(which zsh)

Configuration

Configure bootstrap behavior in ~/.configsync/config.yaml:

~/.configsync/config.yaml

bootstrap:

script: ~/.configsync/bootstrap.sh # Custom path (default)

auto_run: false # Skip the confirmation prompt

bootstrap.scriptPath to the bootstrap script (default: ~/.configsync/bootstrap.sh)
bootstrap.auto_runIf true, run the script without prompting for confirmation

Pull Flags

Control bootstrap behavior when pulling:

--skip-bootstrapSkip bootstrap script execution entirely
--rerun-bootstrapForce re-run even if bootstrap has already been executed on this machine
Terminal

# Pull without running bootstrap

configsync pull --skip-bootstrap

# Force re-run bootstrap on an existing machine

configsync pull --rerun-bootstrap

How It Works

  • The bootstrap script is pushed alongside your configs as part of your state.
  • On first pull to a new machine, ConfigSync detects the absence of a marker file and offers to run the script.
  • After a successful run, a marker file is written to prevent re-running on subsequent pulls.
  • Use --rerun-bootstrap to ignore the marker and run again.
  • Use --skip-bootstrap to skip entirely (the marker is not written).

Example: Full Machine Setup

~/.configsync/bootstrap.sh

#!/bin/bash

set -e

# Install Homebrew if missing

if ! command -v brew &> /dev/null; then

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

fi

# Install packages

brew bundle install --file=~/.config/Brewfile --no-lock

# Restore VS Code extensions

cat ~/.config/vscode-extensions.txt | xargs -L 1 code --install-extension

# Clone work repos

mkdir -p ~/git

for repo in api web mobile; do

[ -d ~/git/$repo ] || git clone git@github.com:myorg/$repo.git ~/git/$repo

done

# Set up shell

source ~/.zshrc