Hanzo

Hattori Hanzō: You must have big rats if you need Hattori Hanzo's steel. The Bride: ...Huge.

CachyOS system provisioner powered by Ansible. A single command bootstraps a complete development and gaming machine with idempotent configuration.

Requirements

• CachyOS (Arch-based)
• Internet connection for initial setup

Quickstart

curl -L https://raw.githubusercontent.com/palazzem/hanzo/main/bin/bootstrap.sh | bash

This will:

1. Install uv and ansible-core
2. Clone this repository to ~/.local/src/hanzo
3. Install required Galaxy collections (community.general, kewlfft.aur)
4. Prompt for your name and email (first run only)
5. Run the full provisioning (prompts once for your sudo password)

Usage

After bootstrap, re-run provisioning at any time:

hanzo              # full provisioning run
hanzo --check      # dry run (shows what would change)

For selective provisioning, pass --tags <role> to run a subset of the playbook:

hanzo --tags hardware                  # only the hardware role
hanzo --tags "languages,tools"         # languages + tools
hanzo --list-tags                      # list all available tags

See CLAUDE.md's Role Tags section for the full tag list and dependency notes.

hanzo accepts any flag that ansible-playbook understands.

Configuration

User configuration is stored at ~/.config/hanzo/config.yml:

hanzo_fullname: "Your Name"
hanzo_email: "your@email.com"

Edit this file directly to update your settings. You can also set HANZO_FULLNAME and HANZO_EMAIL as environment variables for unattended provisioning (e.g., in containers) — the bootstrap script will write them to the config file in YAML form, escaping any embedded quotes or backslashes.

Architecture

Hanzo uses Ansible to provision the local machine via ansible-playbook playbook.yml. All operations are idempotent — running hanzo multiple times is safe and will only apply changes that are needed.

• playbook.yml — main entry point, lists roles in dependency order
• ansible.cfg — local connection, become defaults, roles path
• requirements.yml — Galaxy collection dependencies (pinned versions)
• roles/ — one directory per configured domain; each role declares a tag for selective --tags <role> runs

The hardware role is dispatched by ansible_product_name and skipped automatically inside containers (via ansible_virtualization_type).

Development

Clone the repository and install the pre-commit hooks:

git clone https://github.com/palazzem/hanzo.git
cd hanzo
pre-commit install

Run linters locally:

pre-commit run --all-files

Run the full test suite inside a CachyOS container:

docker build -f tests/Containerfile -t hanzo:test .

The container test runs ansible-playbook --check in two stages — once without ~/.config/hanzo/config.yml (exercises the graceful missing-config path) and once with it (exercises the identity-injection path).

Contribute

This tool provisions my personal CachyOS setup. You may use this repository as a base to create your own configuration. I'll be glad to accept any PR that:

• Fixes bugs or issues in the current implementation
• Improves the Ansible role structure or provisioning logic
• Enhances or makes me aware of different provisioning approaches

I will not merge pull requests that add new development tools, but I will be grateful if you can discuss about it in the issue tracker.

See CLAUDE.md for the task authoring contract.

License

BSD 2-Clause. See LICENSE for details.