Skip to content

common: add system-level config file - #26118

Merged
ngxson merged 7 commits into
ggml-org:masterfrom
jcmdln:config-precedence
Aug 12, 2026
Merged

common: add system-level config file#26118
ngxson merged 7 commits into
ggml-org:masterfrom
jcmdln:config-precedence

Conversation

@jcmdln

@jcmdln jcmdln commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Overview

Currently running llama-cpp tools (llama-cli, llama-bench, llama-embedding, etc) require passing many CLI flags. In some cases, these commands require the same config options, such as defining multi-gpu scenarios, threads, parallel, api-key, etc.

The existing mechanism is models-preset but this only works for llama-server and is a portable, shareable config format. Administrators of multiple machines are missing the ability to define per-node configs independent of models-preset, instead needing to include this in init system configs, shell aliases or some other mechanism.

Instead of duplicating these values or smuggling them into other systems, let's add config precedence re-using the same ini config libraries that models-preset uses so that:

  1. CLI flags have the highest precedence

  2. ENV vars have the second-highest precedence

  3. System and User configs have the lowest precedence

    • Linux/BSD/Mac
      • /etc/llama.cpp/config.ini < ${XDG_CONFIG_HOME:-~/.config}/llama.cpp/config.ini
    • Windows
      • %PROGRAMDATA%\llama.cpp\config.ini < %APPDATA%\llama.cpp\config.ini

Here is an example of what flags an operator might want to set for a particular node:

# ~/.config/llama.cpp/config.ini

# Disabled
ui = off
warmup = off

# API
host = 0.0.0.0
port = 8080
api-key = foobar

# Host-specific throughput tuning
batch-size = 2048
ubatch-size = 2048
flash-attn = on
cache-type-k = q8_0
cache-type-v = q8_0
mmap = off

# Host-specific hardware details
device = Vulkan0,Vulkan1
main-gpu = 1
parallel = 2
threads = 16

Requirements

@jcmdln
jcmdln requested a review from a team as a code owner July 25, 2026 16:58

@ngxson ngxson left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also missing docs about this feature

Comment thread common/common.h
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jul 26, 2026
@jcmdln
jcmdln requested a review from ngxson July 26, 2026 00:14
@jcmdln jcmdln changed the title common: Add CLI > ENV > models-presets > INI precedence common: Add host config file to compliment models-presets Jul 27, 2026
@jcmdln jcmdln changed the title common: Add host config file to compliment models-presets common: Add host config file Jul 28, 2026
@jcmdln
jcmdln force-pushed the config-precedence branch from 05ab3c1 to e18f92b Compare July 29, 2026 19:44
1. CLI flags have the highest precedence
2. ENV vars have the second-highest precedence
3. System and User configs have the lowest precedence
   - Linux/BSD/Mac
     - /etc/llama.cpp/config.ini < ${XDG_CONFIG_HOME:-~/.config}/llama.cpp/config.ini
   - Windows
     - %PROGRAMDATA%\llama.cpp\config.ini < %APPDATA%\llama.cpp\config.ini
@jcmdln
jcmdln force-pushed the config-precedence branch from e18f92b to 3fa1bff Compare August 2, 2026 19:45
@jcmdln

jcmdln commented Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

I believe I have completed the requested changes. Anything else to improve or is this looking better?

@ngxson

ngxson commented Aug 12, 2026

Copy link
Copy Markdown
Collaborator

sorry for the delay, I'll push my changes directly to this PR

@jcmdln
jcmdln force-pushed the config-precedence branch from 3fa1bff to a537279 Compare August 12, 2026 20:35
@ngxson

ngxson commented Aug 12, 2026

Copy link
Copy Markdown
Collaborator

@jcmdln I'm taking over this PR and please do not push any further commits

here are quite many correctness issues that it would be better if I resolve it myself

@ngxson
ngxson force-pushed the config-precedence branch from a537279 to 1b4b677 Compare August 12, 2026 20:44
@ngxson ngxson changed the title common: Add host config file common: add system-level config file Aug 12, 2026

@ngxson ngxson left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all UBs are fixed and behaviors are well-documented in ‎docs/preset.md

@ngxson
ngxson merged commit 8e7f22b into ggml-org:master Aug 12, 2026
22 of 28 checks passed
brittlewis12 pushed a commit to brittlewis12/llama.cpp that referenced this pull request Aug 17, 2026
* common: Add CLI > ENV > models-presets > INI precedence

1. CLI flags have the highest precedence
2. ENV vars have the second-highest precedence
3. System and User configs have the lowest precedence
   - Linux/BSD/Mac
     - /etc/llama.cpp/config.ini < ${XDG_CONFIG_HOME:-~/.config}/llama.cpp/config.ini
   - Windows
     - %PROGRAMDATA%\llama.cpp\config.ini < %APPDATA%\llama.cpp\config.ini

* fix UB

* use common_get_env

* ignore_unknown_keys

* nits

* add docs

---------

Co-authored-by: Xuan Son Nguyen <son@huggingface.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants