Strix Halo Setup Tool

A setup assistant for AMD Strix Halo (gfx1151) machines running Ubuntu 24.04+. It helps get a fresh machine into a working state for AI inference and general infrastructure use, and helps existing users verify and correct their configuration.

It was primarily designed for and tested on the Minisforum MS-S1 MAX, and ships with researched, hardware-aware defaults for ROCm and the AI inference services it can install. Other Strix Halo systems share the same APU and should largely benefit, but the defaults are tuned for the MS-S1 MAX.

Design principles

• Assist, don't enforce. Detect, inform, confirm — in that order.
• Every service is optional. Install what you need, skip the rest.
• Non-destructive by default. Backups before edits, no silent deletes.
• Self-contained. Copy the tool folder to the machine, run it, delete it when done. Nothing is installed system-wide by the tool itself.
• Zero runtime dependencies. Python 3.12+ stdlib only. No pip, no venv.

Install

Recommended — download a release. Grab the latest strix-halo-setup-<version>.zip from the Releases page, copy it to the target machine, unzip, and run it:

unzip strix-halo-setup-*.zip
cd strix-halo-setup
python3 setup.py

The release archive contains only the tool — no research, docs, or tests. Nothing is installed system-wide; delete the folder when you're done.

From source. The tool lives in strix-halo-setup/. Clone or download this repository and run it from that folder:

cd strix-halo-setup
python3 setup.py

On first run, the tool writes sensible defaults to config.toml and shows a welcome screen. Change paths (compose directory, shared models directory) from Settings, and configure host-level options from the Host menu.

Options

Flag	Purpose
--no-color	Disable ANSI colors (useful for logs/pipes)
--reset-state	Remove state.toml so the tool re-discovers everything

Requirements

• Ubuntu 24.04+ (tested on 26.04 LTS)
• Kernel ≥ 6.18.4 for gfx1151 stability
• Python 3.12+ (ships with Ubuntu 24.04+)
• sudo access for host-level changes

Repository layout

.
├── strix-halo-setup/        # The setup tool — this is what a release ships
│   ├── setup.py             # Entry point
│   ├── lib/                 # Internal modules
│   ├── templates/           # Service definitions (TOML, one per service)
│   │   ├── docker-compose/
│   │   ├── native/
│   │   └── distrobox/
│   └── CHANGELOG.md         # Versioned change history (Keep a Changelog)
├── scripts/                 # Standalone utilities + release packaging
├── tests/                   # unittest suite (GRUB parser, config system)
├── docs/                    # User-facing reference docs and setup guides
├── research/                # Research findings — background for the defaults
├── .github/workflows/       # CI: builds + publishes a release zip on each v* tag
└── CODEBASE_MAP.md          # Architecture, module map, template schema

CODEBASE_MAP.md at the repository root is the authoritative reference for architecture, module responsibilities, and the template schema. The research/ directory documents the reasoning behind the tool's hardware-specific defaults (ROCm/gfx1151 env vars and flags, FHS path layouts, installer internals) — a useful read if you are doing similar work on Strix Halo hardware.

Scope

Not in scope:

• BIOS modification (advisory only)
• Multi-user / SSH key / sudo config
• ROCm driver or firmware management
• Maintenance of third-party services after install

Testing

python3 -m unittest discover tests

The test suite covers two areas:

• GRUB parsing — because corrupting /etc/default/grub can render the machine unbootable.
• Interactive config system — config option parsing, selector validation, config item building, finalization, TOML writer extensions, and persistence round-trips.

All other behavior is validated by manual testing on the target hardware.

Releasing

Releases are built automatically by CI. To cut one:

1. Bump TOOL_VERSION in strix-halo-setup/lib/config.py and add a dated section to strix-halo-setup/CHANGELOG.md.
2. Commit, then tag and push: git tag v0.16.0 && git push origin v0.16.0.

The Release workflow runs the tests, verifies the tag matches TOOL_VERSION, and publishes strix-halo-setup-<version>.zip/.tar.gz to a GitHub Release. Build the same artifacts locally with scripts/package.sh.

License

Released under the MIT License.