<div align="center"> <center> <a href="https://github.com/megabyte-labs/install.doctor"> <img width="320" alt="Install Doctor logo" src="https://gitlab.com/megabyte-labs/install.doctor/-/raw/master/docs/logo-full.png" /> </a> </center> </div> <div align="center"> <center><h1 align="center"><i></i>Install Doctor - Cross-Platform Desktop Provisioning<i></i></h1></center> <center><h4 style="color: #18c3d1;">Maintained by <a href="https://megabyte.space" target="_blank">Megabyte Labs</a></h4><i></i></center> </div> <div align="center"> <a href="https://megabyte.space" title="Megabyte Labs homepage" target="_blank"> <img alt="Homepage" src="https://img.shields.io/website?down_color=%23FF4136&down_message=Down&label=Homepage&logo=home-assistant&logoColor=white&up_color=%232ECC40&up_message=Up&url=https%3A%2F%2Fmegabyte.space&style=for-the-badge" /> </a> <a href="https://github.com/megabyte-labs/install.doctor/blob/master/docs/CONTRIBUTING.md" title="Learn about contributing" target="_blank"> <img alt="Contributing" src="https://img.shields.io/badge/Contributing-Guide-0074D9?logo=github-sponsors&logoColor=white&style=for-the-badge" /> </a> <a href="https://app.slack.com/client/T01ABCG4NK1/C01NN74H0LW/details/" title="Chat with us on Slack" target="_blank"> <img alt="Slack" src="https://img.shields.io/badge/Slack-Chat-e01e5a?logo=slack&logoColor=white&style=for-the-badge" /> </a> <a href="https://app.element.io/#/room/#install.doctor:matrix.org" title="Chat with the community via Matrix.org" target="_blank"> <img alt="Matrix" src="https://img.shields.io/matrix/install.doctor:matrix.org?logo=matrix&logoColor=white&style=for-the-badge" /> </a> <a href="https://github.com/megabyte-labs/install.doctor" title="GitHub mirror" target="_blank"> <img alt="GitHub" src="https://img.shields.io/badge/Mirror-GitHub-333333?logo=github&style=for-the-badge" /> </a> <a href="https://gitlab.com/megabyte-labs/install.doctor" title="GitLab repository" target="_blank"> <img alt="GitLab" src="https://img.shields.io/badge/Repo-GitLab-fc6d26?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgAQMAAABJtOi3AAAABlBMVEUAAAD///+l2Z/dAAAAAXRSTlMAQObYZgAAAHJJREFUCNdNxKENwzAQQNEfWU1ZPUF1cxR5lYxQqQMkLEsUdIxCM7PMkMgLGB6wopxkYvAeI0xdHkqXgCLL0Beiqy2CmUIdeYs+WioqVF9C6/RlZvblRNZD8etRuKe843KKkBPw2azX13r+rdvPctEaFi4NVzAN2FhJMQAAAABJRU5ErkJggg==&style=for-the-badge" /> </a> </div>

<br/><h4 align="center"><strong>A performant, cross-platform desktop provisioning system combining application settings, themes, and automated software installation.</strong></h4><br/>

Overview
Quick Start
Environment Variables
Architecture
- Provisioning Flow
- Dependencies
Chezmoi-Based
Security Focused
Cross-Platform
Gas Station
Chezmoi
- Resetting Chezmoi
Contributing
- Affiliates
License

Overview

Install Doctor is a cross-platform development environment provisioning system that combines application settings, theme files, and a performant software installer written with ZX. It uses Chezmoi to manage dotfiles and apply configuration changes across systems.

The project is built around the philosophy that you should be able to reformat your computer and fully restore it by storing stateful data in an encrypted S3 bucket and automating desktop configuration. It supports macOS, most Linux distributions, and has Windows support on the roadmap.

Install Doctor is intended for:

Power users who want to maximize efficiency by incorporating popular open-source tools into their stack
Distro hoppers who want consistent tooling across macOS, Windows, and Linux
Automation enthusiasts who want to reformat and restore their systems with minimal effort
CLI users who want a portable, reproducible terminal environment
Security-conscious users who regularly reformat and need fast, reliable reprovisioning

Quick Start

To provision your workstation with interactive prompts:

bash <(curl -sSL https://install.doctor/start)

Headless Installation

To run completely unattended with no interactive prompts (all prompts auto-proceed with defaults after a 30-second timeout):

HEADLESS_INSTALL=true bash <(curl -sSL https://install.doctor/start)

For full control over the headless installation:

HEADLESS_INSTALL=true \
  SOFTWARE_GROUP=Full \
  SUDO_PASSWORD=your_password \
  FULL_NAME="Your Name" \
  PRIMARY_EMAIL="you@example.com" \
  bash <(curl -sSL https://install.doctor/start)

Using a Fork

If you fork this repository and would like to use your fork as the source, set the START_REPO environment variable:

# GitHub shorthand (user/repo)
START_REPO=my-gh-user/my-fork-name bash <(curl -sSL https://install.doctor/start)

# Full git URL
START_REPO=git@gitlab.com:my-user/install.doctor.git bash <(curl -sSL https://install.doctor/start)

# GitHub username only (assumes repo name is install.doctor)
START_REPO=my-gh-user bash <(curl -sSL https://install.doctor/start)

Quick Start Notes

Tested on latest versions of Archlinux, CentOS, Debian, Fedora, macOS, and Ubuntu
The quick start script is the preferred method of provisioning
All interactive prompts have timeouts and will auto-proceed with sensible defaults
Windows support is on the roadmap

Environment Variables

The following environment variables can be used to customize the provisioning process:

| Variable | Description | Default | |---|---|---| | START_REPO (or REPO) | Git repository URL or GitHub user/repo shorthand | megabyte-labs/install.doctor | | HEADLESS_INSTALL | Skip all interactive prompts and use defaults | unset | | SOFTWARE_GROUP | Software group to install: Basic, Server, Standard, or Full | Full | | SUDO_PASSWORD | Sudo password for automated passwordless sudo setup | unset (prompts with 30s timeout) | | CI or TEST_INSTALL | Enable CI mode with predefined test defaults | unset | | NO_RESTART | Prevent automatic reboots after system updates | unset | | FULL_NAME | User's full name for git config and other tools | unset | | PRIMARY_EMAIL | User's primary email address | unset | | AGE_PASSWORD | Passphrase for decrypting Age-encrypted secrets | unset | | DEBUG_MODE (or DEBUG) | Enable verbose logging and debug output | unset | | KEEP_GOING | Continue provisioning even if errors occur | unset | | ANSIBLE_PROVISION_VM | Qubes only: Name of the VM used for provisioning | provision | | NO_INSTALL_HOMEBREW | Skip Homebrew installation entirely | unset |

For a full list of variables, see the Customization and Secrets documentation.

Architecture

Provisioning Flow

bash <(curl -sSL https://install.doctor/start)
  |
  v
scripts/provision.sh (main orchestrator)
  |-- ensureBasicDeps()     - Install system packages (curl, git, etc.)
  |-- ensureHomebrew()      - Install and configure Homebrew
  |-- setupPasswordlessSudo() - Temporary passwordless sudo (with 30s timeout)
  |-- cloneChezmoiSourceRepo() - Clone/update the Install Doctor repository
  |-- ensureHomebrewDeps()  - Install Chezmoi, Gum, Glow, Node.js, ZX
  |-- initChezmoiAndPrompt() - Initialize Chezmoi configuration
  |-- runChezmoi()          - Apply dotfiles and run provisioning scripts
  |     |
  |     v
  |   home/.chezmoiscripts/
  |     |-- run_before_01-prepare.sh      - System preparation
  |     |-- run_before_02-homebrew.sh     - Homebrew setup
  |     |-- run_before_03-decrypt-age-key.sh - Secret decryption
  |     |-- run_before_04-requirements.sh - System requirements
  |     |-- run_before_05-system.sh       - System tweaks
  |     |-- run_after_01-pre-install.sh   - Pre-install tasks
  |     |-- run_after_10-install.sh       - Software installation
  |     |-- run_after_15-chezmoi-system.sh - System-level chezmoi
  |     |-- run_after_20-post-install.sh  - Post-install configuration
  |     |-- run_after_24-cleanup.sh       - Cleanup tasks
  |
  |-- removePasswordlessSudo() - Remove temporary sudo privileges
  |-- handleRequiredReboot()   - Reboot if system updates require it
  v
  Done

Dependencies

The following tools are installed automatically during provisioning:

| Dependency | Required | Descript

Install.doctor

Install / Use

README

Table of Contents