diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index eab06fcb8..23a612eb9 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -76,6 +76,7 @@ nav:
       - Zerotier VPN: guides/mesh-vpn.md
       - How to disable Secure Boot: guides/secure-boot.md
       - Flake-parts: guides/flake-parts.md
+      - Nixos-rebuild: guides/nixos-rebuild.md
       - macOS: guides/macos.md
       - Contributing:
           - Contributing: guides/contributing/CONTRIBUTING.md
@@ -84,6 +85,7 @@ nav:
 
       - Writing a Service Module: guides/services/community.md
       - Writing a Disko Template: guides/disko-templates/community.md
+      - Nixos-rebuild: guides/nixos-rebuild.md
       - Migrations:
           - Migrate from clan modules to services: guides/migrations/migrate-inventory-services.md
           - Facts Vars Migration: guides/migrations/migration-facts-vars.md
diff --git a/docs/site/guides/nixos-rebuild.md b/docs/site/guides/nixos-rebuild.md
new file mode 100644
index 000000000..6a92d9446
--- /dev/null
+++ b/docs/site/guides/nixos-rebuild.md
@@ -0,0 +1,68 @@
+# Can I still use `nixos-rebuild`?
+
+**Yes, you can still use `nixos-rebuild` with clan!**
+
+Clan is built on top of standard `NixOS` and uses `nixos-rebuild` internally.
+However, there are important considerations when using `nixos-rebuild` directly instead of `clan machines update`.
+
+## Important Considerations
+
+!!! warning "Vars Must Be Uploaded First"
+    If your configuration uses clan vars, failing to run `clan vars upload` before `nixos-rebuild` will result in missing secrets and potentially broken services.
+
+!!! info "Build Host Configuration"
+    Clan automatically handles build host configuration based on your machine settings.
+    When using `nixos-rebuild` manually, you need to specify `--build-host` and `--target-host` options yourself.
+
+## How Clan Uses nixos-rebuild
+
+Clan doesn't replace `nixos-rebuild` - it enhances it. When you run `clan machines update`, clan:
+
+1. Generates and uploads secrets/variables (if any)
+2. Uploads the flake source to the target/build host (if needed)
+3. Runs `nixos-rebuild switch` with the appropriate options
+4. Handles remote building and deployment automatically
+
+Under the hood, clan executes commands like:
+
+```bash
+nixos-rebuild switch --fast --build-host builtHost --flake /path/to/flake#machine-name
+```
+
+## When You Need `clan vars upload`
+
+If your clan configuration uses **variables (vars)** - generated secrets, keys, or configuration values - you **must** run `clan vars upload` before using `nixos-rebuild` directly.
+
+### Systems that use vars include:
+
+- Any `clanModules` with generated secrets (zerotier, borgbackup, etc.)
+- Custom generators that create passwords or keys
+- Services that need shared configuration values
+
+### Systems that don't need vars:
+
+- Basic NixOS configurations without clan-specific services
+- Static configurations with hardcoded values
+- Systems using only traditional NixOS secrets management
+
+## Manual nixos-rebuild Workflow
+
+When you want to use `nixos-rebuild` directly:
+
+### Step 1: Upload vars (if needed)
+
+```bash
+# Upload secret vars to the target machine
+clan vars upload my-machine
+```
+
+### Step 2: Run nixos-rebuild
+
+```bash
+nixos-rebuild switch --flake .#my-machine --target-host root@target-ip --build-host local
+```
+
+## Related Documentation
+
+- [Update Your Machines](getting-started/update.md) - Using clan's update command
+- [Variables (Vars)](vars/vars-overview.md) - Understanding the vars system