Maintained by Megabyte Labs
A performant, cross-platform desktop provisioning system combining application settings, themes, and automated software installation.
- Overview
- Quick Start
- Environment Variables
- Architecture
- Chezmoi-Based
- Security Focused
- Cross-Platform
- Gas Station
- Chezmoi
- Contributing
- License
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
To provision your workstation with interactive prompts:
bash <(curl -sSL https://install.doctor/start)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)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)- 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
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.
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
The following tools are installed automatically during provisioning:
| Dependency | Required | Description |
|---|---|---|
| Chezmoi | Yes | Dotfile configuration manager |
| Task | Yes | Task runner for parallelization and dependency management |
| ZX / Node.js | Yes | Node.js-based scripting for the software installer |
| Homebrew | Yes | Cross-platform package manager |
| Gum | No | Terminal UI prompt CLI for interactive prompts |
| Glow | No | Markdown renderer for terminal-friendly documentation display |
| Age | No | Encryption tool for Chezmoi secret management |
This project leverages Chezmoi to provide:
- File diffs that show exactly how files are being changed before applying
- Encryption via Age that lets you store private data publicly on GitHub
- Template-based configuration that adapts dotfiles to the current OS, hostname, and user preferences
- Interactive prompts that accept API credentials for services like CloudFlare, GitHub, GitLab, and Slack
This software was built with security as a priority, employing technologies like:
- Firejail - Application sandboxing
- Portmaster - Network monitor and firewall
- Little Snitch - macOS network monitor
- Qubes OS - Security-oriented operating system
Whenever possible, Flatpaks are used as the preferred application type for their sandboxing capabilities. The emphasis on security also drives the emphasis on performance - when you regularly reformat your workstation, fast provisioning is essential.
| Platform | Status | Notes |
|---|---|---|
| macOS | Supported | Intel and Apple Silicon (Rosetta 2 auto-installed) |
| Ubuntu / Debian | Supported | Tested on latest LTS releases |
| Fedora / RHEL | Supported | Tested on latest releases |
| CentOS | Supported | Via yum/dnf |
| Archlinux | Supported | Rolling release |
| OpenSUSE | Supported | Via zypper |
| Alpine | Supported | Via apk |
| Qubes OS | In Progress | Dom0 and AppVM provisioning |
| Windows | Roadmap | Planned via WSL |
| FreeBSD | Roadmap | Not yet implemented |
The project incorporates a custom ZX script that manages software installation across multiple package managers. It uses the software.yml file to determine which package manager to use for each application, preferring the most secure option (e.g., Flatpaks for Linux applications). The installer runs asynchronously where possible for better performance.
A sizable amount of effort went into customizing the popular Sweet theme across platforms. Custom GRUB2 and Plymouth themes are included for a polished boot experience on Linux.
Qubes OS support is in progress, with dom0 provisioning and AppVM configuration being actively developed. See the home/.chezmoiscripts/qubes/ directory for Qubes-specific provisioning scripts.
This project evolved from Gas Station, an Ansible-based provisioning system with hundreds of roles. Some Gas Station Ansible roles are still referenced in software.yml as a fallback installation method. The installer tries lighter methods (Homebrew, Flatpak, etc.) before resorting to Ansible.
This project uses Chezmoi to orchestrate the provisioning process. After the quick start script installs dependencies (including Chezmoi), it hands control to Chezmoi which manages dotfile application and runs provisioning scripts.
To customize this project, refer to the Chezmoi documentation for details on file naming conventions (dot_, run_, encrypted_, etc.).
If there is an error during provisioning or your changes are not being applied, clear Chezmoi's cache and configuration:
rm -rf ~/.config/chezmoi && rm -rf ~/.cache/chezmoiThen re-run the quick start command to reprovision from scratch.
Contributions, issues, and feature requests are welcome! Feel free to check the issues page. If you would like to contribute, please take a look at the contributing guide.
Sponsorship
Dear Awesome Person,
I create open source projects out of love. Although I have a job, shelter, and as much fast food as I can handle, it would still be pretty cool to be appreciated by the community for something I have spent a lot of time and money on. Please consider sponsoring me! Who knows? Maybe I will be able to quit my job and publish open source full time.
Sincerely,
Brian Zalewski
Below you will find a list of services we leverage that offer special incentives for signing up for their services through our special links:
Copyright (c) 2020-2025 Megabyte LLC. This project is MIT licensed.
