Getting started

Set up your development environment with kit. Download the command, review the setup plan, and let kit install and configure your tools. You do not need to learn Nix or write any configuration to get started.

Before you begin

You will need:

• A Mac or a Windows PC with support for Windows Subsystem for Linux (WSL 2).
• Administrator access for system changes.
• An internet connection to download your tools.
• Your name and the email address you want to use for Git commits.

Save your work before starting. Windows may need to restart when enabling WSL.

Already using Nix?

kit is designed to set up a managed development environment, not migrate an existing one. If it detects an unsupported Nix installation or conflicting configuration, it will stop rather than overwrite it. You do not need to remove other WSL distributions to use kit.

1. Download kit

Download the executable for your operating system and architecture from a kit release on GitHub Releases. CLI releases use SemVer tags such as kit/0.0.2. Configuration bundles use CalVer tags such as bundle/2026.09.0. Pass only the CalVer value to setup and update: the setup examples below use --version 2026.09.0.

Preview downloads

This preview trusts GitHub and HTTPS. It does not check release signatures or hashes. Use a test machine or VM while evaluating it.

macOS

Download kit and open Terminal. If you saved it in Downloads, run:

cd ~/Downloads
chmod +x ./kit
./kit --version

Windows

Download kit.exe and open PowerShell. If you saved it in Downloads, run:

cd "$HOME\Downloads"
.\kit.exe --version

Run the command on Windows, not inside an existing WSL distribution.

2. Review the setup plan

Preview what kit will do without making changes:

macOS

./kit setup --version 2026.09.0 --dry-run

Windows

.\kit.exe setup --version 2026.09.0 --dry-run

The plan is specific to your machine. It explains what will be installed, where your configuration will live, and whether administrator approval or a restart is needed.

On macOS, kit configures your existing account using Nix, nix-darwin, and Home Manager. On Windows, it sets up a dedicated WSL development environment without replacing your other distributions.

3. Run setup

When you are ready, run setup without --dry-run:

macOS

./kit setup --version 2026.09.0

Windows

.\kit.exe setup --version 2026.09.0

Review the plan and confirm that you want to proceed. Follow the prompts to enter your name, Git email, and preferences. On Windows, you will also choose a Linux username for your development environment; on macOS, kit uses your existing account.

kit downloads the requested release and installs your tools. You may be asked to approve system changes or confirm the Nix installation separately.

Asked to restart Windows?

Restart your PC, open PowerShell, and run the same setup command again. kit will check the prerequisites and continue setup.

Keep secrets out of your configuration

Your Git email is used for commit attribution, not authentication. Do not enter passwords, API keys, or access tokens as setup preferences. Sign in to individual tools using their own login flows after setup.

4. Open your development environment

Once setup reports success:

macOS

Open a new Terminal window so your shell picks up the installed tools and configuration.

Windows

Open the Builder Kit distribution from Windows Terminal. This is where you will run your development tools and work on your projects.

Check your Git identity:

git --version
git config --get user.name
git config --get user.email

Your name and email should match the values you entered during setup. You are ready to start a project!

If you use GitHub or coding agents, follow each tool’s sign-in instructions before using features that require an account. kit installs tools, but does not supply subscriptions or credentials.

Keep your tools up to date

Run management commands from Terminal on macOS or PowerShell on Windows. On Windows, use kit.exe rather than running the command inside WSL.

Choose a newer version from GitHub Releases. There is no automatic “latest” selection. For example, if a 2026.10.0 release has been published, check it with:

kit update --version 2026.10.0 --check

To install that release:

kit update --version 2026.10.0

kit shows the proposed changes and asks for confirmation before applying them. Updates can change package versions and behavior, so review the plan before proceeding.

Running from your download folder

If kit is not on your command path, use the executable directly: ./kit on macOS or .\kit.exe in PowerShell.

Need help?

If setup stops, read the reported reason before retrying. kit will not overwrite an unrelated configuration or automatically repair an unhealthy Nix installation.

• Command not found: open a new terminal, or run the executable directly from the folder where you downloaded it.
• Restart required: restart Windows and rerun setup.
• Already managed: use kit update --version <release> instead of running setup again.
• Conflicting configuration or failed installation: preserve your existing files and the error output. Do not delete configuration directories just to bypass a check.

Ask for help in GitHub Discussions. Include your operating system, the command you ran, and the relevant error message. Remove personal information and secrets before posting.