LLama-GUI

Requirements

• Python 3.9+
• pip and virtual environment support (python -m venv)
• Internet access (for release metadata/downloads, optional app updates, and optional Chat web search)
• A supported OS/architecture for the prebuilt llama.cpp binaries you want to install

Supported prebuilt backends vary by platform: - Windows: CPU, CUDA, Vulkan, SYCL, HIP - macOS: Apple Silicon (Metal, optional KleidiAI) and Intel CPU builds - Linux: CPU, Vulkan, ROCm, OpenVINO (depends on architecture)

One-command install

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/thomas9120/LLama-GUI/main/online_installers/install-online.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/thomas9120/LLama-GUI/main/online_installers/install-online.ps1 | iex

The online installer clones Llama GUI into ~/LLama-GUI on macOS/Linux or %USERPROFILE%\LLama-GUI on Windows, installs the Python dependencies, and starts the app. To install somewhere else, set LLAMA_GUI_INSTALL_DIR before running the command. To install without starting the app, set LLAMA_GUI_NO_START=1.

On Windows, the installer also creates a Llama GUI desktop shortcut. The shortcut starts the local Python server and opens the browser after the app is reachable.

Manual install

1. Clone this repository:

git clone https://github.com/thomas9120/LLama-GUI.git
cd LLama-GUI

1. Install Python dependencies into the local virtual environment:

./install.sh

Windows: - windows_install.bat

If macOS or Linux reports zsh: permission denied when running a helper script, restore the executable bit and rerun the command:

chmod +x install.sh mac_linux_start.sh mac_linux_silent_start.sh

1. Start the app:

./mac_linux_start.sh

Platform launch helpers: - Windows: windows_start.bat or windows_startsilent.bat - macOS/Linux: ./mac_linux_start.sh or ./mac_linux_silent_start.sh

1. Open http://127.0.0.1:5240 in your browser.
2. In Install, choose a version + backend, then click Install.
3. Put .gguf files in models/ (or click Open Models), or use the Hugging Face downloader in Quick Launch.
4. In Quick Launch, select a model, keep the beginner defaults or choose a profile, and click Launch.
5. Open Chat to talk to the running server. Enable Web Search when you want the model to search the web before answering.
6. Use Configure when you want full flag-by-flag control.

Install With Pinokio

If you use Pinokio, you can install and launch Llama GUI through the separate one-click launcher repo:

thomas9120/llama-gui-pinokio

The Pinokio launcher clones this app, installs the Python dependencies, and starts the local web UI. Llama GUI's own Install tab still manages llama.cpp backend downloads, models, presets, and server launches.

Install By Platform

Install

• Install/update/repair llama.cpp binaries
• Backend and release selectors auto-reflect the installed state
• Quick folder access: Open Models and Open llama.cpp
• Maintenance action: Remove llama.cpp Files
• App updater actions:
• Check App Updates
• Update App from GitHub
• If the app updater says local changes are blocking the update, Windows users can close the app, run stash-updates.bat from the Llama GUI folder, then start the app and try Update App from GitHub again. This runs git stash -u, which saves local changes instead of deleting them.

Quick Start

Screenshots

Sampler Presets

Sampler presets are available in both Quick Launch and the Sampling section in Configure.

Includes: - built-in presets: Neutral, Balanced, Creative, Precise - custom preset Save, Load, Delete - JSON Import / Export

Current built-ins are tuned to approximate KoboldCpp's simple preset family while keeping the same user-facing preset names: - Neutral: neutralized baseline - Balanced: close to KoboldCpp Simple Balanced - Creative: close to KoboldCpp Simple Creative - Precise: tuned toward KoboldCpp Simple Logical

Storage behavior: - custom sampler presets are stored in browser localStorage - export creates portable .json files - import accepts single-preset or multi-preset JSON

Quick Launch, Configure, and Chat sampler controls all use the same shared sampler state, so decimal values and preset changes stay synchronized across tabs.

Note: loading a full app preset can overwrite sampler values because samplers are part of the full flag set.

Configure

• Flag browser with category accordions
• Search across category names, flags, option names, and submenu labels
• Expand All, Collapse All, and Clear controls
• Beginner-oriented descriptions, More info, and Beginner tip
• Command preview before launch
• Custom Launch Args textarea for advanced raw llama.cpp flags not yet exposed as UI controls
• Custom args support shell-like quoting, warn when they duplicate UI-managed flags, and block launch if the input cannot be parsed
• Server URL preview when using llama-server
• Live server stats bar when running llama-server

Default-friendly behavior includes: - -fit set to on - -c context default set to 16000 - llama-server selected as the default tool

Backend Mismatch (CUDA/Vulkan/SYCL/HIP/Metal/ROCm/OpenVINO)

Symptoms: - launch crashes immediately - backend/DLL related errors in output

Fix: - reinstall with a backend that matches your hardware/drivers - use Install -> Repair Install if runtime files are incomplete - if unsure, test with CPU backend first

API

• Shows OpenAI-compatible endpoint overview for the current server address
• Provides copy-ready snippets (cURL, Python SDK, JavaScript)
• Useful for quickly connecting local apps/agents to llama-server
• Includes an opt-in Remote Access panel that starts a Cloudflare tunnel for the Llama GUI control panel only after you click Start Tunnel

Troubleshooting