Installation

← Home

• Two binaries
• Recommended: per-platform native channel
• Direct download
• CLI-only
• First launch on macOS
• First launch on Windows
• Updating
• Build from source
• System requirements
• Project configuration (solarxy.toml)

Two binaries

Solarxy ships as two independent binaries:

• solarxy - GUI viewer (window, PBR rendering, sidebar, inspection).
• solarxy-cli - terminal companion (analyze / TUI report, update orchestration, GUI launcher).

Most users want both. The native channels below install both side-by-side. CLI-only paths are listed separately.

After installing, head to the Quickstart for the five-minute path from launch to your first review marker.

Recommended: per-platform native channel

Platform	Command	What you get
macOS (any arch)	brew install --cask koljam/solarxy/solarxy	GUI + CLI. Auto-clears Gatekeeper quarantine.
Linux (any distro)	flatpak install flathub dev.koljam.solarxy	GUI via Flathub. Auto-updates through GNOME Software / KDE Discover.
Windows	winget install Koljam.Solarxy	MSI install of GUI; adds Start Menu entry and PATH. (Per-build ProductCode is extracted from the signed MSI on each stable tag and submitted to microsoft/winget-pkgs by .github/workflows/winget-release.yml.)

Each handles updates natively - no separate self-update step.

Direct download

Pre-built artifacts are published on every tagged release at github.com/marko-koljancic/solarxy/releases:

Platform	File	Install
macOS (Apple Silicon)	Solarxy-X.Y.Z-aarch64.dmg	Open the DMG, drag to Applications. See First launch on macOS.
macOS (Intel)	Solarxy-X.Y.Z-x86_64.dmg	Same as above.
Windows x64	solarxy-X.Y.Z-x86_64-pc-windows-msvc.msi	Double-click; click through SmartScreen (see First launch on Windows).
Linux x86_64	Solarxy-X.Y.Z-x86_64.AppImage	chmod +x and run. Bundles its own GL stack - works on Fedora 42 / Ubuntu 24.04 without extra packages.

Linux aarch64 AppImages remain deferred to v0.7.0+ (pending a stable upstream appimagetool arm64 binary). The x86_64 AppImage works on aarch64 hosts under qemu / Box64 but is not officially supported.

CLI-only

For terminal-only workflows (CI, scripts, headless servers):

# Homebrew (macOS + Linux)
brew install koljam/solarxy/solarxy-cli

# Shell installer (macOS + Linux, places binary in ~/.local/bin)
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/marko-koljancic/solarxy/releases/latest/download/solarxy-cli-installer.sh | sh

# PowerShell installer (Windows, when the MSI is overkill)
powershell -c "irm https://github.com/marko-koljancic/solarxy/releases/latest/download/solarxy-cli-installer.ps1 | iex"

Make sure ~/.local/bin is on your PATH (most Linux distros set this in ~/.profile; macOS users may need to add it to their shell rc).

Upgrading from v0.5.x or earlier? Your config.toml upgrades cleanly - new sections ([review], [dock], [view] in v0.6.0) default via #[serde(default)], so nothing needs to be deleted or migrated. If you originally installed via cargo install (pre-0.5.0 release-candidate builds), the old binary at ~/.cargo/bin/solarxy-cli is not removed automatically - delete it by hand for a clean layout.

solarxy-cli self-updates with solarxy-cli --update when installed via the shell / PowerShell installer. On Homebrew or Flatpak it instead prints the correct brew upgrade / flatpak update command - running axoupdater against a package-managed install would corrupt it.

First launch on macOS

If you used the Homebrew Cask, Gatekeeper quarantine has already been cleared. Skip ahead to using the app.

If you downloaded the .dmg directly, Solarxy is shipped ad-hoc signed - macOS Gatekeeper blocks the first launch.

Recommended: double-click Install CLI.command inside the mounted DMG. It clears the quarantine attribute on /Applications/Solarxy.app and symlinks solarxy-cli into /usr/local/bin/. After the sudo prompt, open Solarxy.app in Applications - no further prompts.

Manual bypass (if you skip the CLI installer): macOS 15 no longer shows an inline "Open Anyway" button in the first-launch dialog.

1. Double-click Solarxy.app. macOS says "Solarxy cannot be opened because it cannot be verified." Click Done.
2. Open System Settings → Privacy & Security → Security. Click Open Anyway next to the Solarxy line.
3. Confirm with your password / Touch ID.
4. Launch Solarxy.app again and click Open in the final confirmation dialog.

macOS remembers the choice - subsequent launches do not prompt.

First launch on Windows

The MSI is unsigned - Windows SmartScreen shows "Windows protected your PC" on first run. Click More info → Run anyway. Verify the SHA-256 checksum published alongside the MSI on the release page if in doubt.

Code signing (Apple Developer certificate + Azure Trusted Signing) is on the roadmap.

Updating

The GUI's Help → Check for Updates… menu detects how Solarxy was installed and shows the right command - brew upgrade, winget upgrade, a Flathub link, or a direct release page link.

For the CLI, run solarxy-cli --update - it self-updates when installed via the shell installer, and prints the right package-manager command otherwise. See CLI Reference → Self-update for the full behaviour matrix.

Install source	What --update does
Shell installer / PowerShell installer / portable .zip	Self-update via axoupdater
Homebrew formula	Prints brew upgrade koljam/solarxy/solarxy-cli
Flatpak (dev.koljam.solarxy)	Prints flatpak update dev.koljam.solarxy

Build from source

If you want a platform we don't ship binaries for, or you're hacking on the code:

1. Install the Rust toolchain from rustup.rs. MSRV: Rust 1.92, Edition 2024.

2. Clone and build:

   git clone https://github.com/marko-koljancic/solarxy.git
   cd solarxy
   cargo build --release

3. Binaries land at:

   • GUI: target/release/solarxy
   • CLI: target/release/solarxy-cli

   Copy them anywhere on your PATH.

A dist profile (cargo build --profile dist) inherits from release with lto = "fat" and matches the official packaging.

System requirements

• CPU: x86_64 with AVX2 + FMA (Intel Haswell 2013+, AMD Excavator 2015+ or later) - release builds embed these feature flags. Apple Silicon (aarch64-apple-darwin) builds target apple-m1.
• GPU: any wgpu-compatible backend - Vulkan, Metal, DirectX 12, or WebGPU. Most GPUs from 2016+ qualify.
• OS: macOS 14+, Windows 10 21H2+, or a modern Linux distribution with Wayland or X11.

To verify a working install:

solarxy --version       # GUI
solarxy-cli --version   # CLI
solarxy-cli --about     # version, repository, and license

Project configuration (solarxy.toml)

Studios that integrate Solarxy into a content pipeline can drop a solarxy.toml into the project root to configure per-project validation policy (budgets, rule toggles, filename → category mapping). It's checked into version control so the whole team shares the same gates.

For IDE autocomplete + inline validation, add this line as the first non-blank line:

#:schema https://raw.githubusercontent.com/marko-koljancic/solarxy/main/schemas/solarxy-config.v1.json

The JSON Schema is auto-generated from the Rust source (schemas/solarxy-config.v1.json in the repo; regeneration steps in schemas/README.md).

To point the CLI at a specific config without dropping it next to the model, use --config <PATH> or the $SOLARXY_CONFIG environment variable. See Configuration for the full schema, every section, and the discovery order.

See also: CLI Reference · Configuration · Troubleshooting · User Guide