From 67c89e00c5dfb3b5076331c84d7f4504ecd11556 Mon Sep 17 00:00:00 2001 From: Josh Palmer Date: Mon, 5 Jan 2026 00:22:15 +0100 Subject: [PATCH] docs: add Nix installation guide and navigation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Expand docs/nix.md from runtime-only to full installation guide - Reference nix-clawdbot as the recommended Nix setup path - Add "Installation" section to docs.json navigation (wizard, nix, docker, setup) - Add Nix link to README quick links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 2 +- docs/docs.json | 10 +++++++- docs/nix.md | 66 +++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 65 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3d16f988a..cd600de6f 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, iMe If you want a personal, single-user assistant that feels local, fast, and always-on, this is it. -Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Docker (optional): [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/clawd +Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · FAQ: [`docs/faq.md`](docs/faq.md) · Wizard: [`docs/wizard.md`](docs/wizard.md) · Nix: [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [`docs/docker.md`](docs/docker.md) · Discord: https://discord.gg/clawd Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**. diff --git a/docs/docs.json b/docs/docs.json index d03c9c041..2a6c4b5a2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -27,11 +27,19 @@ "pages": [ "index", "onboarding", - "wizard", "clawd", "faq" ] }, + { + "group": "Installation", + "pages": [ + "wizard", + "nix", + "docker", + "setup" + ] + }, { "group": "Core Concepts", "pages": [ diff --git a/docs/nix.md b/docs/nix.md index 9fad17e3c..1e32cf449 100644 --- a/docs/nix.md +++ b/docs/nix.md @@ -1,26 +1,64 @@ --- -summary: "Running Clawdbot under Nix (config, state, and packaging expectations)" +summary: "Install Clawdbot declaratively with Nix" read_when: - - Building Clawdbot with Nix - - Debugging Nix-mode behavior + - You want reproducible, rollback-able installs + - You're already using Nix/NixOS/Home Manager + - You want everything pinned and managed declaratively --- -# Nix mode + +# Nix Installation + +The recommended way to run Clawdbot with Nix is via **[nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** — a batteries-included Home Manager module. + +## Quick Start + +Paste this to your AI agent (Claude, Cursor, etc.): + +```text +I want to set up nix-clawdbot on my Mac. +Repository: github:clawdbot/nix-clawdbot + +What I need you to do: +1. Check if Determinate Nix is installed (if not, install it) +2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix +3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot) +4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine +5. Fill in the template placeholders and run home-manager switch +6. Verify: launchd running, bot responds to messages + +Reference the nix-clawdbot README for module options. +``` + +Or see the full guide: **[github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** + +## What you get + +- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned +- Launchd service that survives reboots +- Plugin system with declarative config +- Instant rollback: `home-manager switch --rollback` + +--- + +## Nix Mode Runtime Behavior + +When `CLAWDBOT_NIX_MODE=1` is set (automatic with nix-clawdbot): Clawdbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows. Enable it by exporting: -``` +```bash CLAWDBOT_NIX_MODE=1 ``` On macOS, the GUI app does not automatically inherit shell env vars. You can also enable Nix mode via defaults: -``` +```bash defaults write com.clawdbot.mac clawdbot.nixMode -bool true ``` -## Config + state paths +### Config + state paths Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`. @@ -30,11 +68,11 @@ Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store. -## Runtime behavior in Nix mode +### Runtime behavior in Nix mode -- Auto-install and self-mutation flows should be disabled. -- Missing dependencies should surface Nix-specific remediation messages. -- UI surfaces a read-only Nix mode banner when present. +- Auto-install and self-mutation flows are disabled +- Missing dependencies surface Nix-specific remediation messages +- UI surfaces a read-only Nix mode banner when present ## Packaging note (macOS) @@ -47,3 +85,9 @@ apps/macos/Sources/Clawdbot/Resources/Info.plist `scripts/package-mac-app.sh` copies this template into the app bundle and patches dynamic fields (bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM packaging and Nix builds (which do not rely on a full Xcode toolchain). + +## Related + +- [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide +- [Wizard](./wizard.md) — non-Nix CLI setup +- [Docker](./docker.md) — containerized setup