Get Q/AI running on
Windows and Mac

This guide gets the Q/AI studio running from an extracted release ZIP, including on a removable drive. You do not need Git for the standard setup. Q/AI runs local text chat, supported Stable Diffusion image models, speech recognition and speech output through a browser interface on your computer.

Internet is required for first setup. This archive contains application source and installers and a bundled Mac speech engine. Other engines and model weights are downloaded. Setup downloads a portable Node.js runtime, backend engines and frontend dependencies. Mac setup also downloads a starter speech model; choose other models separately. After those assets are present, local generation can work offline with web search disabled.

1 Requirements and storage

For a removable installation, use a writable external SSD or other storage with adequate free space. Slow USB sticks and memory cards can cause very long setup and model loads. FAT32 cannot hold individual files of 4 GB or larger. NTFS is preferable for Windows-only use; APFS is preferable for Mac-only use. exFAT can share files across both systems, but has no Unix symlinks and may be slower with many small dependency files. The installers contain fallbacks; test the complete installation on your drive.

The app folder can be portable, but drivers, Microsoft runtimes, browser preferences, temporary files, OS paging and optional Homebrew packages can live on the host. Moving the folder does not make the installation independent of the other computer's hardware and OS.

2 Download and extract the entire archive

1. Obtain q-ai-VERSION-setup.zip and SHA256SUMS.txt from the same trusted release. The checksum can detect a damaged or mismatched download; it is not a publisher signature.
2. On Windows, right-click the ZIP and choose Extract All. On Mac, double-click it in Finder. Extract directly onto the intended drive, or move the whole extracted folder there.
3. Use a short writable folder such as D:\AI\q-ai or /Volumes/My AI Drive/q-ai. You can rename the top-level versioned folder to q-ai. Avoid protected folders, cloud-synchronized folders, and launching files from inside a ZIP preview.
4. Open this SETUP.html from the extracted folder. Confirm windows.bat, mac.command, mac.sh, app and scripts are beside it. Keep the folder tree intact.

Optional download verification

Run from the folder holding the ZIP and checksum. Substitute the actual ZIP filename:

Windows PowerShell:

Get-FileHash '.\q-ai-VERSION-setup.zip' -Algorithm SHA256
Get-Content '.\SHA256SUMS.txt'

Mac Terminal:

shasum -a 256 -c SHA256SUMS.txt

Compare the Windows hash against the checksum entry, or require OK on Mac. The archive also includes RELEASE-MANIFEST.json with individual payload file hashes.

3 Test your storage before installing

Use the included Q/AI Drive Check app before downloading engines and models to a USB stick, SD/microSD card, external HDD or SSD. It runs offline without building anything or installing developer tools. Test each device with the computer, reader, cable and USB port you plan to use.

1. Connect the device. Select its volume in Drive Check, or browse to an existing writable folder on that device. Confirm the drive name and capacity. The app can run from your computer while testing a different drive. Benchmarking does not require administrator permission.
2. Enter the size of a model you expect to use, in decimal GB (for example 6.6). This sets the estimated loading time and suitability guidance; it does not download that model.
3. Choose Quick for an initial screen, then Standard for comparing promising devices. Quick uses a 256 MiB temporary dataset; Standard uses 1 GiB; Extended uses 3 GiB. Leave at least the dataset size plus 256 MiB and extra space for small test files. Review the displayed write budget, then click Start read + write test. A slow device may take several minutes.
4. Keep the device connected until the test and cleanup finish. Drive Check writes only new files in a uniquely named test folder, verifies them, then removes its own files. Existing files are preserved. Use Cancel and wait for cleanup if you need to stop.
5. Save the JSON report when prompted. Repeat with each device using the same profile and connection; the comparison table retains saved results. Select a row to read the reasons behind its rating. Changing the model-size field updates the estimates without rerunning the test.

Read the result: green indicates a promising storage choice for the selected model size; yellow indicates tradeoffs or cautions; red indicates a poor fit or a failed check to investigate. Look at estimated model-read time, free-space headroom, and small-file performance as well as the dot. FAT32 cannot store a single model file of 4 GB or larger. These are storage estimates: Drive Check does not measure GPU/RAM suitability, generation speed, or the device's entire capacity. A cancelled test does not establish that the device is defective.

Do not format a drive to run this test. The separate Format as exFAT action erases the selected volume and is unnecessary for benchmarking. Custom formatting in the bundled Mac app requires a separately configured signed helper. After choosing a device, keep or move the whole Q/AI folder onto it and continue with Windows or Mac setup below.

For methodology, report handling and formatting details, see the Drive Check documentation.

4 Windows setup

1. Connect the internet and close earlier Q/AI instances. Before launching, stop unrelated services using backend ports 8080 or 10086: the launcher attempts to terminate processes on those ports.
2. Double-click windows.bat in the extracted folder. If Windows displays a security prompt, confirm the download source before allowing it. Do not disable Windows security globally.
3. At the First-Time Setup prompt, press a key. Keep the terminal open. Setup downloads portable Node.js/npm, image engines, llama.cpp, whisper.cpp, the Kokoro runtime, and frontend dependencies, then builds the web interface. Downloads can take a while and require internet access.
4. If asked to install the Microsoft Visual C++ x64 runtime, approve the administrator prompt if you want setup to install this host prerequisite. The app itself normally runs without administrator rights.
5. Complete any final setup prompt. The launcher opens your browser, usually at http://localhost:1420. If port 1420 is busy, it selects a free port from 1421–1499. Use the address printed in the terminal.
6. Leave the terminal open and continue to model selection below. Subsequent launches use the same windows.bat; intact runtimes are reused.

If double-clicking closes the window before you can read an error, open PowerShell in the extracted folder and run .\windows.bat. To run setup directly for repair:

powershell -NoProfile -ExecutionPolicy Bypass -File '.\scripts\setup\setup.ps1'

This changes the execution policy only for that PowerShell process. If organizational policy blocks scripts or executable downloads, follow your organization's software approval process.

5 Mac setup

1. Confirm the Mac has Apple Silicon and an OS suitable for the pinned image binary. Connect the internet, close earlier Q/AI instances, and stop unrelated services using backend ports 8080/10086.
2. In Finder, open mac.command. It starts the same launcher as mac.sh. If macOS refuses to open a downloaded script, verify the source and use the Terminal method below. The ZIP is source plus scripts, not a signed or notarized Mac application.
3. Press Enter at First-Time Setup. Setup downloads the native portable Node.js runtime, Metal image backend, llama.cpp text backend and Kokoro runtime, installs frontend dependencies and builds the UI. It also installs the bundled, hash-verified Whisper speech engine and downloads a roughly 60 MB starter English model. The standard path does not install Git or a CoreML Python environment.
4. Speech engine verification or starter-model download failures stop setup with an error. Correct the reported problem and rerun the launcher. Complete setup prompts and keep Terminal open.
5. The browser opens at the printed localhost address, usually port 1420. If necessary, open that address manually. For later sessions, open mac.command again.

Terminal method and permissions

Open Terminal, type cd with a trailing space, drag the extracted Q/AI folder from Finder into Terminal, and press Return. Alternatively use a quoted path:

cd "/Volumes/My AI Drive/q-ai"
bash mac.sh

This does not require an executable permission on the launcher. On filesystems supporting Unix permissions, you can also run chmod +x mac.command mac.sh and open mac.command. If security still blocks a downloaded engine, use the exact warning and System Settings → Privacy & Security to review it; approve only files from a source you trust. Do not remove quarantine recursively from unrelated directories or disable Gatekeeper.

Mac speech recognition without development tools

The archive includes statically linked Apple Silicon Whisper CLI and server binaries with embedded Metal shaders. They need only macOS system libraries. Setup verifies their hashes, tests that both engines start, copies them into app/speech-backend/mac/metal/, and automatically downloads Whisper Base English Q5 into app/speech-models/. No Homebrew, Git, Python, Xcode or external library installation is required. Internet is required for the starter model during first setup.

Open Speech-to-Text, select Whisper Base English Q5, and record or import a short clip. Allow browser microphone access when recording. Add multilingual or larger Whisper models through Model Manager. The included English model is a starter, not a requirement to use English exclusively.

If you have an earlier Q/AI installation, extract this new release and use its launcher to install speech, or run bash scripts/setup/setup-whisper.sh from its folder. The bundled build's source, license and binary hashes are documented in the speech bundle notes. This is an attributed prebuilt fork distribution; it is not claimed to be an official ggml-org Mac CLI release.

Optional Apple Neural Engine and CoreML

Metal is the default GPU backend. CoreML/ANE is an advanced optional image path with separate model requirements. It requires Git and a supported Python 3.9–3.11 installation; the dedicated script installs PyTorch and Apple's dependencies. Run it only if you want those components:

bash scripts/setup/setup-coreml-npu.sh

If Python selection fails, set COREML_SETUP_PYTHON to an installed compatible Python executable as described by that script. Standard Metal/chat use does not need this step.

6 Choose and load models

Open Model Manager and choose the model type before importing or downloading. The app provides curated recommendations and estimates text-model memory fit for Hugging Face results. These are starting points, not proof that every architecture, quantization or engine version is compatible.

1. Use the Model Manager download/import controls, or copy complete model files into the correct folder while they are unloaded. Do not import a model as it is still downloading.
2. Choose Text Chat or Image Generation, select the model and load it. Unload another active runtime first if the app blocks switching; engines are normally mutually exclusive to preserve memory.
3. For text, start with a 2,048- or 4,096-token context. If a model exceeds dedicated VRAM, use CPU inference or fewer GPU layers. Do not request all GPU layers merely because the file fits on the drive.
4. Wait for readiness and test a short request. Keep the terminal visible for loader errors and actual backend selection. A successful CPU fallback does not establish that GPU acceleration is working.

Not every Hugging Face model is directly usable. Original Transformers repositories, separate diffusion components, LoRAs, standalone VAEs and text encoders are not interchangeable with complete models. New architectures may need a newer compatible llama.cpp backend. Check the main README's supported-model table and the model publisher's instructions and license.

Text chat currently limits explicit context settings to 32,768 tokens and each response to 4,096 tokens. A publisher's larger context specification does not remove these app limits. Reasoning models may require additional integration; a memory-fit badge alone cannot validate that behavior.

7 Verify the installation and offline use

1. Confirm the UI opens at the launcher's printed address and shows your expected hardware.
2. Load a small model, generate a response, and verify the active engine and model in the terminal or status display. For text, http://localhost:1420/api/llm/status should report ready: true after loading. Substitute the actual frontend port.
3. Test any desired image, speech and TTS capability online once. Their models and first-use assets are separate downloads.
4. Turn off web search. Disconnect the network, restart Q/AI, load the installed model and repeat the test. Search, model browsing/downloads and missing first-use assets still require internet.

The web frontend listens on all network interfaces, whereas the text engine binds to localhost. Keep inbound firewall access blocked unless you intend to expose the UI to other machines. This package does not configure authentication or secure public internet hosting.

8 Removable drives and saved data

Keep the whole extracted folder on the drive. Downloads and most persistent app data are stored beneath it. The launchers resolve their own location, so a changed Windows drive letter is normally fine. A Mac may request removable-volume access for Terminal; approve access to the intended drive.

Windows and macOS need different engine binaries. First launch on a new OS can download its engines and switch frontend dependencies. Reusing the folder on another machine does not guarantee compatible drivers or memory. Do not run the same folder simultaneously from multiple computers.

To stop: unload the active model, press Ctrl+C in the launcher terminal, and wait for processes and file writes to finish. Close files opened from the drive, then safely eject in Windows or Finder. Keep the drive connected throughout model loading and generation because weights may be memory-mapped.

Before installing on another device, use the included Drive Check apps to compare its storage performance and estimated model loading time.

9 Troubleshooting

For a dependency repair after simpler steps fail, review and run scripts/reset/reset.ps1 on Windows or scripts/reset/reset.sh on Mac, then rerun setup. Back up your data first. Avoid deleting the complete app folder to repair a runtime.

10 Updates, removal and support information

Windows upgrade in place: stop Q/AI completely and back up the installation. Extract the new release separately, then copy the contents of its top-level folder into your existing Q/AI folder, replacing matching files without deleting existing model/data folders. Double-click windows.bat. It compares the release version with the last completed Windows setup and runs scripts/setup/setup.ps1 when they differ or no version has been recorded. Setup rebuilds the frontend and records the version only after success; failed setup is retried on the next launch. Installed runtime files remain available for setup to reuse or update as needed. Models, configuration and conversations are retained. Refresh the browser after upgrading, and keep the same browser profile and address (including port) to retain browser-stored preferences.

Update without Git: stop Q/AI and back up the model/data folders above. Extract a new release into a separate folder. Read its release notes, run its setup and test it, then copy the needed model and data folders with the app stopped. Keep the previous folder until you confirm the new one works. Do not overwrite a running install or blindly carry old backend binaries into a new release.

Remove: stop the app and back up what you need, then delete its extracted folder. Host graphics drivers, Visual C++ runtime, optional Homebrew/Python components and browser data are managed separately; deleting Q/AI does not uninstall them.

For a useful support report, record the archive version from RELEASE-MANIFEST.json, OS version, CPU/GPU and memory, filesystem/drive connection, model filename and source, exact terminal error, and whether a small CPU model works. Remove private prompts or paths before sharing logs.

Further reading: main README, Drive Check documentation, platform verification status, and application license. Models and downloaded dependencies have their own licenses. The bundled Mac Drive Check passed native and GUI tests on macOS. The full Q/AI studio and first-run Gatekeeper experience still require validation on the target Mac.