From 1c811ab2b34c244ea65bf1455482fe57c0245e05 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 11:53:54 +0530 Subject: [PATCH 01/17] start an installation script for user onboarding. --- docs/source/builder/nix.md | 5 + docs/source/builder/writing-kernels.md | 28 ++++ install.sh | 178 +++++++++++++++++++++++++ onboard-script-plan.md | 175 ++++++++++++++++++++++++ 4 files changed, 386 insertions(+) create mode 100755 install.sh create mode 100644 onboard-script-plan.md diff --git a/docs/source/builder/nix.md b/docs/source/builder/nix.md index 89daea01..4133b827 100644 --- a/docs/source/builder/nix.md +++ b/docs/source/builder/nix.md @@ -1,5 +1,10 @@ # Using the kernel builder with Nix +> [!NOTE] +> The [install script](writing-kernels.md#quick-install) automates +> the Nix and kernel-builder setup described below. Use these manual +> instructions if you prefer step-by-step control. + The kernel builder uses Nix for building kernels. You can build or run the kernels directly if you have Nix installed on your system. We recommend installing Nix in the following way: diff --git a/docs/source/builder/writing-kernels.md b/docs/source/builder/writing-kernels.md index c9863186..a392f30a 100644 --- a/docs/source/builder/writing-kernels.md +++ b/docs/source/builder/writing-kernels.md @@ -37,6 +37,34 @@ support. ## Setting up environment +### Quick install + +The fastest way to get started is to run the install script. This +installs [Determinate Nix](https://docs.determinate.systems/determinate-nix/) +and `kernel-builder` in a single command: + +```bash +curl -fsSL https://raw.githubusercontent.com/huggingface/kernels/main/install.sh | bash +``` + +This will: + +1. Install Determinate Nix (if not already installed). +2. Configure the Hugging Face binary cache (to avoid building dependencies from + source). +3. Install `kernel-builder` via `nix profile install`. + +To update `kernel-builder` later: + +```bash +nix profile upgrade --all +``` + +For a step-by-step breakdown of what the script does, see +[Using the kernel builder with Nix](nix.md). + +### Cloud environment + In the [`terraform`](https://github.com/huggingface/kernels/tree/main/terraform) directory, we provide an example of programatically spinning up an EC2 instance that is ready with everything needed for you to start developing and building diff --git a/install.sh b/install.sh new file mode 100755 index 00000000..07c90b7b --- /dev/null +++ b/install.sh @@ -0,0 +1,178 @@ +#!/bin/bash +set -euo pipefail + +# kernel-builder installer +# Usage: curl -fsSL https://raw.githubusercontent.com/huggingface/kernels/main/install.sh | bash + +FLAKE_REF="github:huggingface/kernels" +NIX_PROFILE_SCRIPT="/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh" + +# --- Colors (respect NO_COLOR) --- + +if [ -z "${NO_COLOR:-}" ] && [ -t 1 ]; then + BOLD="\033[1m" + GREEN="\033[0;32m" + YELLOW="\033[0;33m" + RED="\033[0;31m" + RESET="\033[0m" +else + BOLD="" + GREEN="" + YELLOW="" + RED="" + RESET="" +fi + +info() { echo -e "${BOLD}${GREEN}==>${RESET} ${BOLD}$1${RESET}"; } +warn() { echo -e "${BOLD}${YELLOW}warning:${RESET} $1"; } +error() { echo -e "${BOLD}${RED}error:${RESET} $1" >&2; } + +# --- Platform detection --- + +detect_platform() { + local os arch + os="$(uname -s)" + arch="$(uname -m)" + + case "$os" in + Linux) os="linux" ;; + Darwin) os="darwin" ;; + *) + error "Unsupported operating system: $os" + exit 1 + ;; + esac + + case "$arch" in + x86_64) arch="x86_64" ;; + aarch64|arm64) arch="aarch64" ;; + *) + error "Unsupported architecture: $arch" + exit 1 + ;; + esac + + PLATFORM="${arch}-${os}" + + case "$PLATFORM" in + x86_64-linux|aarch64-linux|aarch64-darwin) ;; + *) + error "Unsupported platform: $PLATFORM" + echo " Supported platforms: x86_64-linux, aarch64-linux, aarch64-darwin" + exit 1 + ;; + esac + + info "Detected platform: $PLATFORM" +} + +# --- macOS: Xcode check --- + +check_xcode() { + if [ "$(uname -s)" = "Darwin" ]; then + if ! xcode-select -p &>/dev/null; then + warn "Xcode is not installed. It is required for building Metal kernels." + echo " Install it with: xcode-select --install" + fi + fi +} + +# --- Nix --- + +find_nix() { + if command -v nix &>/dev/null; then + return 0 + elif [ -x "/nix/var/nix/profiles/default/bin/nix" ]; then + export PATH="/nix/var/nix/profiles/default/bin:$PATH" + return 0 + fi + return 1 +} + +install_nix() { + if find_nix; then + info "Nix is already installed: $(nix --version)" + return 0 + fi + + info "Installing Determinate Nix..." + curl -fsSL https://install.determinate.systems/nix | sh -s -- install --no-confirm + + # Source the Nix profile so nix is available in this shell. + if [ -f "$NIX_PROFILE_SCRIPT" ]; then + # shellcheck disable=SC1090 + . "$NIX_PROFILE_SCRIPT" + fi + + if ! find_nix; then + error "Nix installation completed but 'nix' was not found in PATH." + echo " Try restarting your shell or running:" + echo " . $NIX_PROFILE_SCRIPT" + exit 1 + fi + + info "Nix installed: $(nix --version)" +} + +# --- Binary cache --- + +configure_cache() { + local substituters + substituters="$(nix show-config 2>/dev/null | grep "^substituters" || true)" + + if echo "$substituters" | grep -q "huggingface.cachix.org"; then + info "Hugging Face binary cache is already configured" + return 0 + fi + + info "Configuring Hugging Face binary cache..." + nix run nixpkgs#cachix -- use huggingface + info "Binary cache configured" +} + +# --- Install kernel-builder --- + +install_kernel_builder() { + info "Installing kernel-builder..." + nix profile install "${FLAKE_REF}#kernel-builder" + + if ! command -v kernel-builder &>/dev/null; then + error "kernel-builder was installed but is not in PATH." + echo " Try restarting your shell or running:" + echo " . $NIX_PROFILE_SCRIPT" + exit 1 + fi + + info "kernel-builder installed: $(kernel-builder --version)" +} + +# --- Main --- + +main() { + echo "" + echo -e "${BOLD}kernel-builder installer${RESET}" + echo "" + + detect_platform + check_xcode + install_nix + configure_cache + install_kernel_builder + + echo "" + echo -e "${BOLD}${GREEN}kernel-builder installed successfully!${RESET}" + echo "" + echo " Next steps:" + echo " 1. Create a new kernel: kernel-builder init my-kernel" + echo " 2. Build your kernel: cd my-kernel && nix run .#build-and-copy -L" + echo " 3. Read the docs: https://huggingface.co/docs/kernels/" + echo "" + echo " To update kernel-builder later:" + echo " nix profile upgrade --all" + echo "" + echo " Note: you may need to restart your shell or run:" + echo " . $NIX_PROFILE_SCRIPT" + echo "" +} + +main diff --git a/onboard-script-plan.md b/onboard-script-plan.md new file mode 100644 index 00000000..2f47f05d --- /dev/null +++ b/onboard-script-plan.md @@ -0,0 +1,175 @@ +# Onboarding Script Plan: `curl | bash` with Nix-first Approach + +## Goal + +Provide a single command that gets a new kernel developer from zero to a working +`kernel-builder` installation: + +```bash +curl -fsSL https://raw.githubusercontent.com/huggingface/kernels/main/install.sh | bash +``` + +The key insight: install Determinate Nix first, then install `kernel-builder` +through Nix via `nix profile install`. This avoids requiring users to have Rust +installed and sidesteps Rust toolchain version issues entirely. + +--- + +## Architecture + +``` +install.sh (entry point) + | + +--> 1. Check/install Nix (Determinate installer) + +--> 2. Configure binary cache (huggingface cachix) + +--> 3. Install kernel-builder via nix profile + +--> 4. Print next-steps summary +``` + +--- + +## Implementation Steps + +### Step 1: Create `install.sh` at repo root + +A POSIX-compatible shell script with the following sections: + +#### Prerequisites + +`kernel-builder` is already exposed per-system at +`packages..kernel-builder` in the root `flake.nix` (line 208), so +`nix profile install github:huggingface/kernels#kernel-builder` already works. +The flake declares the `huggingface.cachix.org` substituter in `nixConfig`, so +the binary is fetched from cache when Nix trusts the flake's nixConfig +(Determinate Nix does this by default). If cache misses are an issue, consider +also setting `packages..default = kernel-builder` so that +`nix profile install github:huggingface/kernels` (without the fragment) works +too. + +#### 1a. Preamble & environment detection + +- `set -euo pipefail` +- Detect OS (`uname -s`) and architecture (`uname -m`) +- Define color helpers for terminal output (with `NO_COLOR` support) +- Bail out on unsupported platforms (e.g., Windows/WSL detection with a pointer + to WSL-specific instructions if needed) +- Supported targets: `x86_64-linux`, `aarch64-linux`, `aarch64-darwin` +- **macOS**: check for `xcode-select -p` and **warn** (not error) if Xcode is + not installed — it's required for Metal kernels but not for the install itself + +#### 1b. Check if Nix is already installed + +- Check for `nix` in `PATH` or the Determinate Nix default locations + (`/nix/var/nix/profiles/default/bin/nix`) +- If found: print version, skip to step 1d +- If not found: proceed to step 1c + +#### 1c. Install Determinate Nix + +- Print a clear message: "Installing Determinate Nix..." +- Run the Determinate installer: + ```bash + curl -fsSL https://install.determinate.systems/nix | sh -s -- install --no-confirm + ``` +- The `--no-confirm` flag avoids a second interactive prompt (the user already + opted in by running our script). Consider making this configurable via an + environment variable (e.g., `KERNEL_BUILDER_INTERACTIVE=1` to drop + `--no-confirm`). +- Source the Nix profile so `nix` is available in the current shell: + ```bash + . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh + ``` +- Verify `nix --version` succeeds after install + +#### 1d. Configure the Hugging Face binary cache + +This is critical for usability — without the cache, users will build PyTorch +from source (hours of compilation). + +- Check if the `huggingface.cachix.org` substituter is already configured + (parse `nix show-config` output) +- If not configured, run: + ```bash + nix run nixpkgs#cachix -- use huggingface + ``` +- This adds the cache to the Nix config without requiring `cachix` to be + permanently installed + +#### 1e. Install kernel-builder via Nix profile + +```bash +nix profile install github:huggingface/kernels#kernel-builder +``` + +This pulls the pre-built `kernel-builder` binary from the Hugging Face cache +(no Rust compilation needed). It also installs shell completions (bash/fish/zsh) +that are already set up in the Nix derivation. + +- Verify `kernel-builder --version` succeeds after install + +#### 1f. Print success message and next steps + +``` +kernel-builder installed successfully! + +Next steps: + 1. Create a new kernel: kernel-builder init my-kernel + 2. Build your kernel: cd my-kernel && nix run .#build-and-copy -L + 3. Read the docs: https://huggingface.co/docs/kernels/ + +To update kernel-builder later: + nix profile upgrade --all + +Note: you may need to restart your shell or run: + . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh +``` + +--- + +### Step 2: Update documentation + +- **`docs/source/builder/writing-kernels.md`**: The primary landing page for + kernel authors. Update the "Setting up environment" section (currently only + mentions Terraform) to lead with the `curl | bash` one-liner as the + recommended way to get started. +- **`docs/source/builder/nix.md`**: Keep as the detailed Nix reference. Add a + note at the top that the install script handles all of this automatically, + linking back to `writing-kernels.md`. +- Keep the existing manual instructions in `nix.md` as-is for users who prefer + step-by-step control. + +--- + +## File Changes Summary + +| File | Action | Description | +|------|--------|-------------| +| `install.sh` | **Create** | The main `curl \| bash` onboarding script | +| `docs/source/builder/writing-kernels.md` | **Edit** | Add install one-liner to "Setting up environment" | +| `docs/source/builder/nix.md` | **Edit** | Add note that install script automates these steps | + +--- + +## Open Questions + +1. **`--no-confirm` for Determinate installer** — Should we always pass this, or + ask the user? The Determinate installer's own prompt is informative (shows + what it will do). Passing `--no-confirm` is more frictionless but less + transparent. + +2. ~~**Pinning the flake ref**~~ **Resolved**: use `main` as the install ref + (`github:huggingface/kernels#kernel-builder`). `main` is defined as always + pointing to the latest release — i.e., tags are cut from `main`. + +3. ~~**Updating kernel-builder**~~ **Resolved**: document the upgrade command + in the success message and in `writing-kernels.md`. No `--upgrade` flag in + the script — just tell users to run: + ``` + nix profile upgrade --all + ``` + +4. **Flake nixConfig trust** — When a user runs `nix profile install` on a flake + with `nixConfig.extra-substituters`, Nix may prompt them to trust it (unless + using Determinate Nix which trusts by default). If using the official Nix + installer on Linux, we may need to configure the cache explicitly before + the `nix profile install` step. The script handles this in step 1d. From b5ceafe4b5908b69f31e9593f48a6110efc6f281 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 12:24:58 +0530 Subject: [PATCH 02/17] fix cache configuration per user. --- install.sh | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/install.sh b/install.sh index 07c90b7b..eb1b9548 100755 --- a/install.sh +++ b/install.sh @@ -116,6 +116,23 @@ install_nix() { # --- Binary cache --- +ensure_trusted_user() { + local user + user="$(whoami)" + local trusted + trusted="$(nix show-config 2>/dev/null | grep "^trusted-users" || true)" + + if echo "$trusted" | grep -qE "(^| )(root|\*|${user})( |$)"; then + return 0 + fi + + info "Adding $user as a trusted Nix user (requires sudo)..." + echo "trusted-users = root $user" | sudo tee -a /etc/nix/nix.conf >/dev/null + sudo pkill nix-daemon || true + # Give the daemon a moment to restart. + sleep 1 +} + configure_cache() { local substituters substituters="$(nix show-config 2>/dev/null | grep "^substituters" || true)" @@ -125,6 +142,8 @@ configure_cache() { return 0 fi + ensure_trusted_user + info "Configuring Hugging Face binary cache..." nix run nixpkgs#cachix -- use huggingface info "Binary cache configured" From e9a18d955825f2c87838af89cc4ae14529217433 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 12:30:11 +0530 Subject: [PATCH 03/17] polish more --- install.sh | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/install.sh b/install.sh index eb1b9548..c869ad09 100755 --- a/install.sh +++ b/install.sh @@ -119,18 +119,17 @@ install_nix() { ensure_trusted_user() { local user user="$(whoami)" - local trusted - trusted="$(nix show-config 2>/dev/null | grep "^trusted-users" || true)" - if echo "$trusted" | grep -qE "(^| )(root|\*|${user})( |$)"; then + # nix show-config outputs: "trusted-users = root" + # Check if the current user (or wildcard *) is already trusted. + if nix show-config 2>/dev/null | grep "^trusted-users" | grep -qwE "(\*|${user})"; then return 0 fi info "Adding $user as a trusted Nix user (requires sudo)..." echo "trusted-users = root $user" | sudo tee -a /etc/nix/nix.conf >/dev/null - sudo pkill nix-daemon || true - # Give the daemon a moment to restart. - sleep 1 + sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true + sleep 2 } configure_cache() { From 2269db8a50ffb39e7b7644a68a265c2600ee3256 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 12:40:02 +0530 Subject: [PATCH 04/17] up --- install.sh | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/install.sh b/install.sh index c869ad09..05c17979 100755 --- a/install.sh +++ b/install.sh @@ -116,21 +116,8 @@ install_nix() { # --- Binary cache --- -ensure_trusted_user() { - local user - user="$(whoami)" - - # nix show-config outputs: "trusted-users = root" - # Check if the current user (or wildcard *) is already trusted. - if nix show-config 2>/dev/null | grep "^trusted-users" | grep -qwE "(\*|${user})"; then - return 0 - fi - - info "Adding $user as a trusted Nix user (requires sudo)..." - echo "trusted-users = root $user" | sudo tee -a /etc/nix/nix.conf >/dev/null - sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true - sleep 2 -} +HF_SUBSTITUTER="https://huggingface.cachix.org" +HF_PUBLIC_KEY="huggingface.cachix.org-1:ynTPbLS0W8ofXd9fDjk1KvoFky9K2jhxe6r4nXAkc/o=" configure_cache() { local substituters @@ -141,10 +128,11 @@ configure_cache() { return 0 fi - ensure_trusted_user - info "Configuring Hugging Face binary cache..." - nix run nixpkgs#cachix -- use huggingface + echo "extra-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null + echo "extra-trusted-public-keys = $HF_PUBLIC_KEY" | sudo tee -a /etc/nix/nix.conf >/dev/null + sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true + sleep 2 info "Binary cache configured" } From 610e5015be971bf736ca61d5cd32efc563f03a3f Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 12:43:00 +0530 Subject: [PATCH 05/17] cachix issues --- install.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/install.sh b/install.sh index 05c17979..d3ae1459 100755 --- a/install.sh +++ b/install.sh @@ -140,7 +140,7 @@ configure_cache() { install_kernel_builder() { info "Installing kernel-builder..." - nix profile install "${FLAKE_REF}#kernel-builder" + nix profile add --accept-flake-config "${FLAKE_REF}#kernel-builder" if ! command -v kernel-builder &>/dev/null; then error "kernel-builder was installed but is not in PATH." From 74c7160440c8e2143ceb84f248137a636dff54e1 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 13:16:02 +0530 Subject: [PATCH 06/17] fix more issues around trusted issues. --- install.sh | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/install.sh b/install.sh index d3ae1459..4c83491b 100755 --- a/install.sh +++ b/install.sh @@ -120,16 +120,16 @@ HF_SUBSTITUTER="https://huggingface.cachix.org" HF_PUBLIC_KEY="huggingface.cachix.org-1:ynTPbLS0W8ofXd9fDjk1KvoFky9K2jhxe6r4nXAkc/o=" configure_cache() { - local substituters - substituters="$(nix show-config 2>/dev/null | grep "^substituters" || true)" - - if echo "$substituters" | grep -q "huggingface.cachix.org"; then + if grep -q "huggingface.cachix.org" /etc/nix/nix.conf 2>/dev/null; then info "Hugging Face binary cache is already configured" return 0 fi info "Configuring Hugging Face binary cache..." - echo "extra-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null + # Use 'trusted-substituters' and 'trusted-public-keys' — these are daemon-level + # settings (written to nix.conf as root) so they don't require the user to be + # in 'trusted-users'. + echo "extra-trusted-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null echo "extra-trusted-public-keys = $HF_PUBLIC_KEY" | sudo tee -a /etc/nix/nix.conf >/dev/null sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true sleep 2 From 8a729053ad24612db3eecedee398d55c6ee6c06d Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 31 Mar 2026 13:33:24 +0530 Subject: [PATCH 07/17] remove plan --- onboard-script-plan.md | 175 ----------------------------------------- 1 file changed, 175 deletions(-) delete mode 100644 onboard-script-plan.md diff --git a/onboard-script-plan.md b/onboard-script-plan.md deleted file mode 100644 index 2f47f05d..00000000 --- a/onboard-script-plan.md +++ /dev/null @@ -1,175 +0,0 @@ -# Onboarding Script Plan: `curl | bash` with Nix-first Approach - -## Goal - -Provide a single command that gets a new kernel developer from zero to a working -`kernel-builder` installation: - -```bash -curl -fsSL https://raw.githubusercontent.com/huggingface/kernels/main/install.sh | bash -``` - -The key insight: install Determinate Nix first, then install `kernel-builder` -through Nix via `nix profile install`. This avoids requiring users to have Rust -installed and sidesteps Rust toolchain version issues entirely. - ---- - -## Architecture - -``` -install.sh (entry point) - | - +--> 1. Check/install Nix (Determinate installer) - +--> 2. Configure binary cache (huggingface cachix) - +--> 3. Install kernel-builder via nix profile - +--> 4. Print next-steps summary -``` - ---- - -## Implementation Steps - -### Step 1: Create `install.sh` at repo root - -A POSIX-compatible shell script with the following sections: - -#### Prerequisites - -`kernel-builder` is already exposed per-system at -`packages..kernel-builder` in the root `flake.nix` (line 208), so -`nix profile install github:huggingface/kernels#kernel-builder` already works. -The flake declares the `huggingface.cachix.org` substituter in `nixConfig`, so -the binary is fetched from cache when Nix trusts the flake's nixConfig -(Determinate Nix does this by default). If cache misses are an issue, consider -also setting `packages..default = kernel-builder` so that -`nix profile install github:huggingface/kernels` (without the fragment) works -too. - -#### 1a. Preamble & environment detection - -- `set -euo pipefail` -- Detect OS (`uname -s`) and architecture (`uname -m`) -- Define color helpers for terminal output (with `NO_COLOR` support) -- Bail out on unsupported platforms (e.g., Windows/WSL detection with a pointer - to WSL-specific instructions if needed) -- Supported targets: `x86_64-linux`, `aarch64-linux`, `aarch64-darwin` -- **macOS**: check for `xcode-select -p` and **warn** (not error) if Xcode is - not installed — it's required for Metal kernels but not for the install itself - -#### 1b. Check if Nix is already installed - -- Check for `nix` in `PATH` or the Determinate Nix default locations - (`/nix/var/nix/profiles/default/bin/nix`) -- If found: print version, skip to step 1d -- If not found: proceed to step 1c - -#### 1c. Install Determinate Nix - -- Print a clear message: "Installing Determinate Nix..." -- Run the Determinate installer: - ```bash - curl -fsSL https://install.determinate.systems/nix | sh -s -- install --no-confirm - ``` -- The `--no-confirm` flag avoids a second interactive prompt (the user already - opted in by running our script). Consider making this configurable via an - environment variable (e.g., `KERNEL_BUILDER_INTERACTIVE=1` to drop - `--no-confirm`). -- Source the Nix profile so `nix` is available in the current shell: - ```bash - . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh - ``` -- Verify `nix --version` succeeds after install - -#### 1d. Configure the Hugging Face binary cache - -This is critical for usability — without the cache, users will build PyTorch -from source (hours of compilation). - -- Check if the `huggingface.cachix.org` substituter is already configured - (parse `nix show-config` output) -- If not configured, run: - ```bash - nix run nixpkgs#cachix -- use huggingface - ``` -- This adds the cache to the Nix config without requiring `cachix` to be - permanently installed - -#### 1e. Install kernel-builder via Nix profile - -```bash -nix profile install github:huggingface/kernels#kernel-builder -``` - -This pulls the pre-built `kernel-builder` binary from the Hugging Face cache -(no Rust compilation needed). It also installs shell completions (bash/fish/zsh) -that are already set up in the Nix derivation. - -- Verify `kernel-builder --version` succeeds after install - -#### 1f. Print success message and next steps - -``` -kernel-builder installed successfully! - -Next steps: - 1. Create a new kernel: kernel-builder init my-kernel - 2. Build your kernel: cd my-kernel && nix run .#build-and-copy -L - 3. Read the docs: https://huggingface.co/docs/kernels/ - -To update kernel-builder later: - nix profile upgrade --all - -Note: you may need to restart your shell or run: - . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh -``` - ---- - -### Step 2: Update documentation - -- **`docs/source/builder/writing-kernels.md`**: The primary landing page for - kernel authors. Update the "Setting up environment" section (currently only - mentions Terraform) to lead with the `curl | bash` one-liner as the - recommended way to get started. -- **`docs/source/builder/nix.md`**: Keep as the detailed Nix reference. Add a - note at the top that the install script handles all of this automatically, - linking back to `writing-kernels.md`. -- Keep the existing manual instructions in `nix.md` as-is for users who prefer - step-by-step control. - ---- - -## File Changes Summary - -| File | Action | Description | -|------|--------|-------------| -| `install.sh` | **Create** | The main `curl \| bash` onboarding script | -| `docs/source/builder/writing-kernels.md` | **Edit** | Add install one-liner to "Setting up environment" | -| `docs/source/builder/nix.md` | **Edit** | Add note that install script automates these steps | - ---- - -## Open Questions - -1. **`--no-confirm` for Determinate installer** — Should we always pass this, or - ask the user? The Determinate installer's own prompt is informative (shows - what it will do). Passing `--no-confirm` is more frictionless but less - transparent. - -2. ~~**Pinning the flake ref**~~ **Resolved**: use `main` as the install ref - (`github:huggingface/kernels#kernel-builder`). `main` is defined as always - pointing to the latest release — i.e., tags are cut from `main`. - -3. ~~**Updating kernel-builder**~~ **Resolved**: document the upgrade command - in the success message and in `writing-kernels.md`. No `--upgrade` flag in - the script — just tell users to run: - ``` - nix profile upgrade --all - ``` - -4. **Flake nixConfig trust** — When a user runs `nix profile install` on a flake - with `nixConfig.extra-substituters`, Nix may prompt them to trust it (unless - using Determinate Nix which trusts by default). If using the official Nix - installer on Linux, we may need to configure the cache explicitly before - the `nix profile install` step. The script handles this in step 1d. From 63a17d7448495897d91cff97bddac0632ad3143b Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 08:17:15 +0530 Subject: [PATCH 08/17] sanboxing relaxed. --- install.sh | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/install.sh b/install.sh index 4c83491b..5e7bc86e 100755 --- a/install.sh +++ b/install.sh @@ -140,7 +140,15 @@ configure_cache() { install_kernel_builder() { info "Installing kernel-builder..." - nix profile add --accept-flake-config "${FLAKE_REF}#kernel-builder" + + local nix_args=(--accept-flake-config) + + # macOS requires relaxed sandboxing to access the Metal compiler. + if [ "$(uname -s)" = "Darwin" ]; then + nix_args+=(--extra-conf "sandbox = relaxed") + fi + + nix profile add "${nix_args[@]}" "${FLAKE_REF}#kernel-builder" if ! command -v kernel-builder &>/dev/null; then error "kernel-builder was installed but is not in PATH." From e68cd5aa29c9a104960d053cff2f164dd4519967 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 08:24:05 +0530 Subject: [PATCH 09/17] remove platform detection. --- install.sh | 40 ---------------------------------------- 1 file changed, 40 deletions(-) diff --git a/install.sh b/install.sh index 5e7bc86e..898221d5 100755 --- a/install.sh +++ b/install.sh @@ -27,45 +27,6 @@ info() { echo -e "${BOLD}${GREEN}==>${RESET} ${BOLD}$1${RESET}"; } warn() { echo -e "${BOLD}${YELLOW}warning:${RESET} $1"; } error() { echo -e "${BOLD}${RED}error:${RESET} $1" >&2; } -# --- Platform detection --- - -detect_platform() { - local os arch - os="$(uname -s)" - arch="$(uname -m)" - - case "$os" in - Linux) os="linux" ;; - Darwin) os="darwin" ;; - *) - error "Unsupported operating system: $os" - exit 1 - ;; - esac - - case "$arch" in - x86_64) arch="x86_64" ;; - aarch64|arm64) arch="aarch64" ;; - *) - error "Unsupported architecture: $arch" - exit 1 - ;; - esac - - PLATFORM="${arch}-${os}" - - case "$PLATFORM" in - x86_64-linux|aarch64-linux|aarch64-darwin) ;; - *) - error "Unsupported platform: $PLATFORM" - echo " Supported platforms: x86_64-linux, aarch64-linux, aarch64-darwin" - exit 1 - ;; - esac - - info "Detected platform: $PLATFORM" -} - # --- macOS: Xcode check --- check_xcode() { @@ -167,7 +128,6 @@ main() { echo -e "${BOLD}kernel-builder installer${RESET}" echo "" - detect_platform check_xcode install_nix configure_cache From 519f74551174bd1e20bd9e27f38596699e8a14b5 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 08:28:22 +0530 Subject: [PATCH 10/17] remove sleep since systemctl already does it. --- install.sh | 1 - 1 file changed, 1 deletion(-) diff --git a/install.sh b/install.sh index 898221d5..59a546ac 100755 --- a/install.sh +++ b/install.sh @@ -93,7 +93,6 @@ configure_cache() { echo "extra-trusted-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null echo "extra-trusted-public-keys = $HF_PUBLIC_KEY" | sudo tee -a /etc/nix/nix.conf >/dev/null sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true - sleep 2 info "Binary cache configured" } From 4b6f21f88b98980fe6d77e33101c5be1a62c1a2e Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 08:55:42 +0530 Subject: [PATCH 11/17] trusted users. --- install.sh | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/install.sh b/install.sh index 59a546ac..03c158d0 100755 --- a/install.sh +++ b/install.sh @@ -87,9 +87,12 @@ configure_cache() { fi info "Configuring Hugging Face binary cache..." - # Use 'trusted-substituters' and 'trusted-public-keys' — these are daemon-level - # settings (written to nix.conf as root) so they don't require the user to be - # in 'trusted-users'. + local user + user="$(whoami)" + # Add the user as a trusted Nix user and configure the binary cache. + # Trusted users can accept flake nixConfig settings (extra-substituters, + # extra-trusted-public-keys) without the daemon ignoring them. + echo "trusted-users = root $user" | sudo tee -a /etc/nix/nix.conf >/dev/null echo "extra-trusted-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null echo "extra-trusted-public-keys = $HF_PUBLIC_KEY" | sudo tee -a /etc/nix/nix.conf >/dev/null sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true From 16059236d9a3ad3718d0f5051396caaf3a1f1d77 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 09:02:50 +0530 Subject: [PATCH 12/17] trusted users ii. --- install.sh | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/install.sh b/install.sh index 03c158d0..173f9e68 100755 --- a/install.sh +++ b/install.sh @@ -79,9 +79,11 @@ install_nix() { HF_SUBSTITUTER="https://huggingface.cachix.org" HF_PUBLIC_KEY="huggingface.cachix.org-1:ynTPbLS0W8ofXd9fDjk1KvoFky9K2jhxe6r4nXAkc/o=" +NIX_CONF_DIR="/etc/nix/nix.conf.d" +HF_CONF="$NIX_CONF_DIR/huggingface.conf" configure_cache() { - if grep -q "huggingface.cachix.org" /etc/nix/nix.conf 2>/dev/null; then + if [ -f "$HF_CONF" ]; then info "Hugging Face binary cache is already configured" return 0 fi @@ -89,12 +91,18 @@ configure_cache() { info "Configuring Hugging Face binary cache..." local user user="$(whoami)" - # Add the user as a trusted Nix user and configure the binary cache. - # Trusted users can accept flake nixConfig settings (extra-substituters, - # extra-trusted-public-keys) without the daemon ignoring them. - echo "trusted-users = root $user" | sudo tee -a /etc/nix/nix.conf >/dev/null - echo "extra-trusted-substituters = $HF_SUBSTITUTER" | sudo tee -a /etc/nix/nix.conf >/dev/null - echo "extra-trusted-public-keys = $HF_PUBLIC_KEY" | sudo tee -a /etc/nix/nix.conf >/dev/null + + # Write a drop-in config file rather than appending to nix.conf. + # This is idempotent and doesn't risk corrupting the main config. + # - trusted-users: allows the user to accept flake nixConfig settings + # - extra-substituters: adds the HF cache + # - extra-trusted-public-keys: trusts the HF cache signing key + sudo mkdir -p "$NIX_CONF_DIR" + sudo tee "$HF_CONF" >/dev/null </dev/null || sudo pkill -HUP nix-daemon || true info "Binary cache configured" } From a18032649712594ec581954895786eaa16aa2b2b Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 09:20:16 +0530 Subject: [PATCH 13/17] trusted users iii. --- install.sh | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/install.sh b/install.sh index 173f9e68..0fa3a1b1 100755 --- a/install.sh +++ b/install.sh @@ -79,11 +79,9 @@ install_nix() { HF_SUBSTITUTER="https://huggingface.cachix.org" HF_PUBLIC_KEY="huggingface.cachix.org-1:ynTPbLS0W8ofXd9fDjk1KvoFky9K2jhxe6r4nXAkc/o=" -NIX_CONF_DIR="/etc/nix/nix.conf.d" -HF_CONF="$NIX_CONF_DIR/huggingface.conf" configure_cache() { - if [ -f "$HF_CONF" ]; then + if nix show-config 2>/dev/null | grep -q "huggingface.cachix.org"; then info "Hugging Face binary cache is already configured" return 0 fi @@ -92,14 +90,11 @@ configure_cache() { local user user="$(whoami)" - # Write a drop-in config file rather than appending to nix.conf. - # This is idempotent and doesn't risk corrupting the main config. - # - trusted-users: allows the user to accept flake nixConfig settings - # - extra-substituters: adds the HF cache - # - extra-trusted-public-keys: trusts the HF cache signing key - sudo mkdir -p "$NIX_CONF_DIR" - sudo tee "$HF_CONF" >/dev/null </dev/null < Date: Wed, 1 Apr 2026 09:33:35 +0530 Subject: [PATCH 14/17] sleep again --- install.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/install.sh b/install.sh index 0fa3a1b1..22c1992d 100755 --- a/install.sh +++ b/install.sh @@ -99,6 +99,7 @@ extra-substituters = $HF_SUBSTITUTER extra-trusted-public-keys = $HF_PUBLIC_KEY EOF sudo systemctl restart nix-daemon 2>/dev/null || sudo pkill -HUP nix-daemon || true + sleep 3 info "Binary cache configured" } From cc0b0f056bbd6fed025f3867f52f19b2eb196d79 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Wed, 1 Apr 2026 09:35:12 +0530 Subject: [PATCH 15/17] remove check --- install.sh | 7 ------- 1 file changed, 7 deletions(-) diff --git a/install.sh b/install.sh index 22c1992d..afeb1f9d 100755 --- a/install.sh +++ b/install.sh @@ -117,13 +117,6 @@ install_kernel_builder() { nix profile add "${nix_args[@]}" "${FLAKE_REF}#kernel-builder" - if ! command -v kernel-builder &>/dev/null; then - error "kernel-builder was installed but is not in PATH." - echo " Try restarting your shell or running:" - echo " . $NIX_PROFILE_SCRIPT" - exit 1 - fi - info "kernel-builder installed: $(kernel-builder --version)" } From 78b8af8f8554505b90118b8a14e07708b3ad1fd9 Mon Sep 17 00:00:00 2001 From: drbh Date: Wed, 1 Apr 2026 17:25:51 -0400 Subject: [PATCH 16/17] feat: add symlink and update config location --- install.sh | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/install.sh b/install.sh index afeb1f9d..53ac2f12 100755 --- a/install.sh +++ b/install.sh @@ -81,23 +81,18 @@ HF_SUBSTITUTER="https://huggingface.cachix.org" HF_PUBLIC_KEY="huggingface.cachix.org-1:ynTPbLS0W8ofXd9fDjk1KvoFky9K2jhxe6r4nXAkc/o=" configure_cache() { - if nix show-config 2>/dev/null | grep -q "huggingface.cachix.org"; then + if sudo nix config show 2>/dev/null | grep -q "huggingface.cachix.org"; then info "Hugging Face binary cache is already configured" return 0 fi info "Configuring Hugging Face binary cache..." - local user - user="$(whoami)" - - # 'extra-trusted-users' appends to the existing trusted-users list. - # Using 'trusted-users' would override the default (root), which could - # break the Nix installation. - sudo tee -a /etc/nix/nix.conf >/dev/null </dev/null </dev/null || sudo pkill -HUP nix-daemon || true sleep 3 info "Binary cache configured" @@ -117,6 +112,9 @@ install_kernel_builder() { nix profile add "${nix_args[@]}" "${FLAKE_REF}#kernel-builder" + # Symlink the kernel-builder binary to /usr/local/bin for easy access + sudo ln -sf "$HOME/.nix-profile/bin/kernel-builder" /usr/local/bin/kernel-builder + info "kernel-builder installed: $(kernel-builder --version)" } From 6c4a107ba2c488ce50b9a19994e0a1e008fd2e08 Mon Sep 17 00:00:00 2001 From: drbh Date: Wed, 1 Apr 2026 17:29:48 -0400 Subject: [PATCH 17/17] feat: also add trusted user --- install.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/install.sh b/install.sh index 53ac2f12..92c70c4d 100755 --- a/install.sh +++ b/install.sh @@ -89,6 +89,7 @@ configure_cache() { info "Configuring Hugging Face binary cache..." sudo tee -a /etc/nix/nix.custom.conf >/dev/null <