mirror of https://github.com/hanzoai/bot.git synced 2026-10-30 17:24:26 +00:00

Files

T

zeekayandHanzo Dev 84e4069c2c docs name the state dir and config file the bot reads: ~/.bot/bot.json

The docs said ~/.hanzo-bot/hanzo-bot.json (and ~/.hanzo-bot-<profile>, hanzo-bot.plugin.json), which nothing reads: src/config/paths.ts resolves ~/.bot, bot.json and ~/.bot-<profile>, and plugins ship bot.plugin.json. Every such path in docs/ now names what the code opens.

Co-authored-by: Hanzo Dev <[email protected]>

2026-09-24 21:12:09 -07:00

3.3 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Install HanzoBot declaratively with Nix

You want reproducible, rollback-able installs

You're already using Nix/NixOS/Home Manager

You want everything pinned and managed declaratively

Nix

Nix Installation

The recommended way to run HanzoBot with Nix is via nix-hanzo-bot — a batteries-included Home Manager module.

Quick Start

Paste this to your AI agent (Claude, Cursor, etc.):

I want to set up nix-hanzo-bot on my Mac.
Repository: github:hanzo-bot/nix-hanzo-bot

What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/hanzo-bot-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, model provider API 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-hanzo-bot README for module options.

📦 Full guide: github.com/hanzo-bot/nix-hanzo-bot

The nix-hanzo-bot repo is the source of truth for Nix installation. This page is just a quick overview.

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 BOT_NIX_MODE=1 is set (automatic with nix-hanzo-bot):

HanzoBot supports a Nix mode that makes configuration deterministic and disables auto-install flows. Enable it by exporting:

BOT_NIX_MODE=1

On macOS, the GUI app does not automatically inherit shell env vars. You can also enable Nix mode via defaults:

defaults write ai.hanzo.bot.mac hanzo-bot.nixMode -bool true

Config + state paths

HanzoBot reads JSON5 config from BOT_CONFIG_PATH and stores mutable data in BOT_STATE_DIR. When needed, you can also set BOT_HOME to control the base home directory used for internal path resolution.

BOT_HOME (default precedence: HOME / USERPROFILE / os.homedir())
BOT_STATE_DIR (default: ~/.bot)
BOT_CONFIG_PATH (default: $BOT_STATE_DIR/bot.json)

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

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)

The macOS packaging flow expects a stable Info.plist template at:

apps/macos/Sources/HanzoBot/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).

nix-hanzo-bot — full setup guide
Wizard — non-Nix CLI setup
Docker — containerized setup

3.3 KiB Raw Permalink Blame History