Install On macOS

Install LexiSuite on macOS

Status, 11/11/2026: not available yet. The macOS installer compiles for macOS and its decisions are tested on Linux, but it has never run on a Mac, and current images carry a note in the macos folder instead of the installer. This page describes how it is designed to work.

The native installer is distributed on the LEXISUITE FAT32 partition of the USB image. macOS 13 and later is the target on Apple silicon and Intel Macs. Use the matching native Panel and Engine payload under suite/macos-aarch64/ (or suite/macos-arm64/) or suite/macos-x86_64/ on the same volume. No Homebrew, source build, Rust compiler, or network connection is needed.

Start from the stick

In Finder open LEXISUITE → macos → Install LexiSuite.command. The launcher opens Terminal and runs macos/LexiSuite-Install; it does not download or execute scripts from the Internet. Select Install for this user for an unprivileged installation, Install for every user to authorize a system-wide installation, Run from the stick, Upgrade, Roll back, Uninstall, or Check this computer. Only the system-wide choice asks for administrator authorization.

You can also run the bundled installer from Terminal (substitute your mount point, which Finder provides):

cd /Volumes/LEXISUITE/macos
./LexiSuite-Install macos-install doctor --media /Volumes/LEXISUITE
./LexiSuite-Install macos-install install --media /Volumes/LEXISUITE
./LexiSuite-Install macos-install upgrade --media /Volumes/LEXISUITE
./LexiSuite-Install macos-install rollback
./LexiSuite-Install macos-install uninstall

--panel-only or --engine-only omits the other program and its service. --no-start writes the binaries and launchd definitions without starting the services. --dry-run inspects the source and selected paths without changing them. For system-wide actions add --all-users (sudo authorization is needed only for actual writes). The installer will not automatically replace an existing installation: use upgrade instead of install.

The Panel opens at http://127.0.0.1:8090 by default. --reachable is a separate opt-in for binding to other computers. If you enable LAN access, configure suitable authentication and network protections before exposing the Panel. Existing settings are preserved when upgrading, so a network binding change should be managed explicitly rather than assumed from an upgrade flag.

Files, data, and services

Scope	Programs	Data, including models	Services
This user	~/Applications/LexiSuite/	~/Library/Application Support/LexiSuite/	~/Library/LaunchAgents/com.lexisuite.{panel,engine}.plist
Every user	/Applications/LexiSuite/	/Library/Application Support/LexiSuite/	/Library/LaunchDaemons/com.lexisuite.{panel,engine}.plist

The installer writes a LexiSuite.webloc shortcut in the matching Applications folder. launchd starts enabled programs when the account logs in (LaunchAgents) or when the system starts (LaunchDaemons). System LaunchDaemons run as the account that authorized the installation, not as root. The system service account must retain access to the selected data directory.

The installer never installs macOS drivers or GPU runtimes. Engine service configuration uses the local models/ directory; the Engine still needs a supported model to serve requests. If none exists, inspect the Engine log in .../LexiSuite/logs/ after adding a model.

Run from the stick without installation

./LexiSuite-Install macos-install run --media /Volumes/LEXISUITE
./LexiSuite-Install macos-install run --media /Volumes/LEXISUITE --data-dir "$HOME/Documents/LexiSuite-Data"

No program files, LaunchAgents, LaunchDaemons, or shortcuts are installed. The binaries run directly from suite/<macOS architecture>/ and data is written only to the selected user-data folder (by default ~/Documents/LexiSuite). The Panel browser page is opened after startup. Use --no-start to inspect the paths without launching programs. Log files are inside the chosen data folder. The USB must stay mounted while its binaries are running.

Upgrade, rollback, and uninstall

upgrade stages the new payload before replacing the programs, stops the managed services, and keeps the prior programs and service definitions at .../LexiSuite/rollback/. Models, settings, keys, and user data remain in their original directory. rollback exchanges the current programs for that previous generation and restores the saved launchd definitions. Only one previous generation is retained. Do not remove the data directory if you may need to roll back.

Uninstall stops managed services, removes program files, launchd plists, and the shortcut. It does not remove models, settings, or keys by default. To delete these as well, first review the data directory printed by the installer and explicitly request:

./LexiSuite-Install macos-install uninstall --delete-data --yes

This permanently deletes the data directory, including models, keys, settings, logs and rollback copies; it cannot be undone. Neither mode changes macOS firewall or other installed applications.

Hardware check

doctor is read-only. On a Mac it reports the operating-system version, processor architecture, physical and logical CPU counts, RAM and unified memory, graphics adapters with the Metal support information reported by macOS, disk space, and whether a matching native payload is on the stick. Apple silicon GPUs share memory with the CPU; the total is not extra dedicated VRAM. Vulkan, CUDA and ROCm depend on separate compatible drivers/runtime libraries and are not installed by LexiSuite.

Release preparation: universal binary

The build uses two separately compiled thin 64-bit Mach-O installer executables, one for aarch64-apple-darwin and one for x86_64-apple-darwin. A standard-library-only fat Mach-O assembly step is available as:

lexipanel-installer macos-install universal \
  --arm64 target/aarch64-apple-darwin/release/lexipanel-installer \
  --x86_64 target/x86_64-apple-darwin/release/lexipanel-installer \
  --output macos/LexiSuite-Install

It validates both thin headers and emits an aligned two-architecture FAT_MAGIC binary. The image/release integrator is responsible for compiling the thin binaries, placing the output and the Install LexiSuite.command launcher into macos/, and producing checksums and signed release metadata. This step does not sign or notarize binaries. macOS Gatekeeper policy may require signed/notarized release artifacts depending on their provenance and local security settings; copying from USB is not a guarantee of exemption.

Current validation boundary

Unit tests exercise isolated temporary homes, synthetic suite payloads, launchd plist structure, install/update/rollback/uninstall/refusal cases, and universal Mach-O header alignment. These are not substitutes for a signed release, a real Mac build, user-login service testing, OS security prompts, or Metal inference testing on Apple hardware.