Webui/server config defaults by ServeurpersoCom · Pull Request #18028 · ggml-org/llama.cpp

ServeurpersoCom · 2025-12-14T12:16:17Z

Make sure to read the contributing guidelines before submitting a PR

server/webui: add CLI support for configuring WebUI defaults

Summary

Implements issue #17940: adds '--webui-config-file' CLI argument and 'LLAMA_WEBUI_CONFIG' environment variable to configure WebUI default settings from the server side.

Problem

WebUI settings are hardcoded in the frontend with no server-side configuration. This causes problems:

Server operators can't set sensible defaults for their deployment
Users must reconfigure settings every time localStorage is cleared
Multi-user servers can't enforce defaults (like disabling auto-file-paste)

Example: Issue #17940 requests ability to set 'pasteLongTextToFileLen: 0' by default, but currently every user must manually configure this in every new browser session.

The TODO that guided this implementation

While exploring the codebase, I found this intentional placeholder in 'server-models.cpp' (lines 6-16):

// TODO: add support for this on web UI
{"role", "router"},
// this is a dummy response to make sure webui doesn't break
{"default_generation_settings", {
    {"params", json{}},  // <-- Empty JSON waiting for implementation
    {"n_ctx", 0},
}},

This empty JSON was left by the original developers as a clear signal for where webui settings should go. This PR completes that TODO.

Backend Changes (C++)

What was added

1. CLI argument ('common/arg.cpp')

New flag: '--webui-config-file '
Loads JSON file with WebUI default settings

2. Environment variable ('server.cpp')

New env var: 'LLAMA_WEBUI_CONFIG'
Accepts JSON string, overrides file config
Example: 'LLAMA_WEBUI_CONFIG='{"pasteLongTextToFileLen":0}''

3. JSON parsing logic ('server.cpp')

Parses config at startup, before any router/child fork
Simple override: env var OR file (env var takes precedence)
Error handling: warn on missing file, error on invalid JSON

4. Expose in /props ('server-models.cpp' + 'server-context.cpp')

Added 'webui_settings' field to '/props' response
Works in both router mode and child mode
Fills in the TODO placeholder mentioned above

How it works

Server startup
  |
  v
Parse LLAMA_WEBUI_CONFIG env var (if set) OR config.json (if provided)
  |
  v
Store result in params.webui_config
  |
  v
Return in /props as webui_settings

The C++ backend is completely agnostic: it doesn't know what settings exist. It just:

Reads JSON
Passes through to frontend

This means adding new WebUI settings never requires C++ changes.

Frontend Changes (TypeScript)

What was added

1. API type ('types/api.d.ts')

Added optional 'webui_settings' field to props response
Type: 'Record<string, string | number | boolean>'

2. Syncable parameters ('services/parameter-sync.ts')

Added 14 WebUI settings to 'SYNCABLE_PARAMETERS':
- pasteLongTextToFileLen
- pdfAsImage
- showThoughtInProgress
- showToolCalls
- disableReasoningFormat
- keepStatsVisible
- showMessageStats
- askForTitleConfirmation
- disableAutoScroll
- renderUserContentAsMarkdown
- autoMicOnEmpty
- pyInterpreterEnabled
- enableContinueGeneration
- showSystemMessage
Updated 'extractServerDefaults()' to merge webui_settings

3. Store integration ('stores/server.svelte.ts' + 'stores/settings.svelte.ts')

Added getter for 'webuiSettings'
Plumbed through to settings store

4. Tests ('parameter-sync.spec.ts')

Test for webui_settings extraction
Validates user-specific settings are filtered out
Uses 'pasteLongTextToFileLen: 0' example from issue

Settings intentionally excluded

These are user-specific and should NOT be server-configurable:

apiKey (personal credentials)
systemMessage (personal prompt)
theme (UI preference)
mcpServers (personal MCP config)
custom (user's custom JSON)

Priority Order

Server operators set defaults, but users keep control:

1. WebUI hardcoded defaults (settings-config.ts)
2. Server config: LLAMA_WEBUI_CONFIG env var OR --webui-config-file
3. User's localStorage (always wins)

This means:

Server can provide sensible defaults
Users can still override anything
No breaking changes

Usage Examples

Config file

# webui-defaults.json
{
  "pasteLongTextToFileLen": 0,
  "pdfAsImage": true,
  "showThoughtInProgress": false
}

./llama-server --webui-config-file webui-defaults.json

Environment variable

LLAMA_WEBUI_CONFIG='{"pasteLongTextToFileLen":0}' ./llama-server

Both (env var overrides file)

LLAMA_WEBUI_CONFIG='{"pdfAsImage":true}' \
  ./llama-server --webui-config-file webui-defaults.json

Check it works

curl http://localhost:8080/props | jq .webui_settings

Testing

Backend

# Create test config
echo '{"pasteLongTextToFileLen":0}' > test.json

# Test file loading
./llama-server --webui-config-file test.json

# Test env var
LLAMA_WEBUI_CONFIG='{"pdfAsImage":true}' ./llama-server

# Check /props
curl http://localhost:8080/props | jq .webui_settings

Frontend

cd tools/server/webui
npm test -- parameter-sync.spec.ts

Backward Compatibility

No breaking changes:

'webui_settings' is optional in /props
Old servers work fine (webui_settings: null or missing)
WebUI falls back to hardcoded defaults
No recompilation needed for existing deployments

What this enables

Now server operators can:

Set deployment-wide defaults without forking
Disable problematic features (like auto-file-paste)
Provide better defaults for their use case
Support multiple configurations via env vars

And adding new configurable settings only requires TypeScript changes: no C++ recompilation needed.

Fixes #17940

ServeurpersoCom · 2025-12-14T12:31:29Z

Testing...

cd /var/www/ia/models
/root/llama.cpp.pascal/build/bin/llama-server \
 -ngl 999 -ctk q8_0 -ctv q8_0 -fa on --mlock -np 4 -kvu --port 8082 \
 --models-max 1 --models-preset backend.ini --webui-config-file frontend.json \
 > llama-server.log 2>&1 &

frontend.json

{
 "showSystemMessage": true,
 "showThoughtInProgress": true,
 "showToolCalls": true,
 "disableReasoningFormat": false,
 "keepStatsVisible": true,
 "showMessageStats": true,
 "askForTitleConfirmation": false,
 "pasteLongTextToFileLen": 0,
 "pdfAsImage": false,
 "disableAutoScroll": false,
 "renderUserContentAsMarkdown": false,
 "autoMicOnEmpty": false,
 "pyInterpreterEnabled": false,
 "enableContinueGeneration": true
}

EDIT: should not contain the sampling parameters

ServeurpersoCom · 2025-12-14T15:39:29Z

It work

common/common.h

common/arg.cpp

tools/server/server.cpp

allozaur

Looking good on my end

ggerganov

Can merge after rebase and green CI. @ngxson up to you

common/arg.cpp

tools/server/server.cpp

tools/server/server-models.cpp

tools/server/server.cpp

common/common.h

ngxson · 2025-12-17T11:15:23Z

Also, you need to re-generate the server docs via llama-gen-docs, and copy-paste it to the ## Usage section of server/README.md

ServeurpersoCom · 2025-12-17T11:38:34Z

I will apply the optimizations and rebase / test

ngxson

Can be merged once you update the docs 👍

tools/server/server.cpp

@ngxson

Add CLI arguments --webui-config (inline JSON) and --webui-config-file (file path) to configure WebUI default settings from server side. Backend changes: - Parse JSON once in server_context::load_model() for performance - Cache parsed config in webui_settings member (zero overhead on /props) - Add proper error handling in router mode with try/catch - Expose webui_settings in /props endpoint for both router and child modes Frontend changes: - Add 14 configurable WebUI settings via parameter sync - Add tests for webui settings extraction - Fix subpath support with base path in API calls Addresses feedback from @ngxson and @ggerganov

ServeurpersoCom · 2025-12-17T14:29:46Z

Docs regenerated. Fun fact: llama-gen-docs initializes my GPU just to write markdown😂

woof-dog · 2025-12-17T14:51:06Z

By the way, this works great! Thank you for implementing this and helping me finally get it through! @mashdragon you will be glad to see this!

If I find the time, I can write up an example for the webui readme (in a separate PR perhaps).

jbone1313 · 2025-12-18T19:04:45Z

@ServeurpersoCom this is not working for me. I verified that the props page has the correct settings and ensured that they actually change when set via the config file. But, the settings in the web UI do not match the props, nor does the web UI behave according to what is set in the props page.

b7472
Windows

ServeurpersoCom · 2025-12-18T19:28:43Z

@ServeurpersoCom this is not working for me. I verified that the props page has the correct settings and ensured that they actually change when set via the config file. But, the settings in the web UI do not match the props, nor does the web UI behave according to what is set in the props page.

b7472 Windows

Your previous WebUI settings can override the server defaults. Server defaults only apply when you first visit the WebUI or after resetting settings.

Else can you clear your browser's localStorage/indexedDB and retry ?
(Browser console, tested on Firefox)

localStorage.clear();
sessionStorage.clear();
indexedDB.deleteDatabase('LlamacppWebui');
setTimeout(() => location.reload(), 1000);

ServeurpersoCom · 2025-12-18T19:52:33Z

There is a bug! "Reset to default" works, but defaults aren't applied on first visit after clearing browser storage. I'm working on a patch

jbone1313 · 2025-12-18T20:03:20Z

Yeah, I just tried "reset to default" and the code you gave me for Firefox. Neither worked. After I cleared all browser data it worked.

While I am here:

Is there a way to force the server defaults to override the previous Web UI settings without having to reset? It would be nice to know that what is set in the defaults will win every time.
Is there a list of the actual names of the settable parameters? I already checked -h and the llama-server readme. The list you posted up-thread has many but not all of them. For example, the new "always show sidebar parameter" is not in that list.

ServeurpersoCom · 2025-12-18T20:33:29Z

1. Is there a way to force the server defaults to override the previous Web UI settings without having to reset? It would be nice to know that what is set in the defaults will win every time.
2. Is there a list of the actual names of the settable parameters? I already checked -h and the llama-server readme. The list you posted up-thread has many but not all of them. For example, the new "always show sidebar parameter" is not in that list.

This is a useful and frequently requested feature in businesses where administrators need complete control, (exactly like GPOs on workstations in an active directory domain). We could add a simple field to the JSON to instruct the WebUI to always apply its default settings (new "prohibit override" feature).
-> Could you create a feature request for this ? But that's not a priority; for now, just click the "reset settings" button must work.
Debugging default values for new webui users and updating missing settings are priorities (what this PR must do) Misc. bug: WebUI, first application of default settings (JSON) #18185

jbone1313 · 2025-12-19T04:56:37Z

RE 1:

I am happy to write up a feature request, but after thinking about this, it seems like this feature needs to be implemented consistently with how this issue will be handled: #18129 (comment) (Misc. bug: Web-Frontend overrides sampling parameters from models preset in router mode), and l imagine that one will be treated with high priority.

I am not a UI expert, but it seems like some elegant and consistent solution could apply to both cases.

Perhaps it could work thus: for a given parameter, the server (either server config defaults or router config.ini) - IF set - is the source of truth unless the parameter is manually set in Web UI. Perhaps the Web UI could show the server-set values as "greyed-out," and when they are manually overridden, they would be shown as "normal." This requires no extra JSON fields, and the UI itself would provide information about where the parameter values are being set.

RE "prohibiting overrides" for enterprise-like cases: perhaps that could be considered low priority and implemented later.

RE 2:

Apologies, but I do not see how that addresses my question 2 above regarding how to determine the actual list of settable parameters we can set in the JSON file.

ServeurpersoCom · 2025-12-19T06:09:43Z

@jbone1313 What you're describing is exactly the design pattern we need for #18129 (sampling params override bug). Server values as source of truth (greyed in UI), with user overrides, and placeholder show the current backend config. Same architecture for both webui settings and sampling parameters. We all independently converged on this.

I've been running shared llama.cpp servers for friends for a long time and wanted this exact behavior. Now deploying more and more at work: proper server governance is critical.

@ngxson

* server/webui: add server-side WebUI config support Add CLI arguments --webui-config (inline JSON) and --webui-config-file (file path) to configure WebUI default settings from server side. Backend changes: - Parse JSON once in server_context::load_model() for performance - Cache parsed config in webui_settings member (zero overhead on /props) - Add proper error handling in router mode with try/catch - Expose webui_settings in /props endpoint for both router and child modes Frontend changes: - Add 14 configurable WebUI settings via parameter sync - Add tests for webui settings extraction - Fix subpath support with base path in API calls Addresses feedback from @ngxson and @ggerganov * server: address review feedback from ngxson * server: regenerate README with llama-gen-docs

@ngxson

* server/webui: add server-side WebUI config support Add CLI arguments --webui-config (inline JSON) and --webui-config-file (file path) to configure WebUI default settings from server side. Backend changes: - Parse JSON once in server_context::load_model() for performance - Cache parsed config in webui_settings member (zero overhead on /props) - Add proper error handling in router mode with try/catch - Expose webui_settings in /props endpoint for both router and child modes Frontend changes: - Add 14 configurable WebUI settings via parameter sync - Add tests for webui settings extraction - Fix subpath support with base path in API calls Addresses feedback from @ngxson and @ggerganov * server: address review feedback from ngxson * server: regenerate README with llama-gen-docs

ServeurpersoCom requested review from allozaur, ggerganov and ngxson as code owners December 14, 2025 12:16

ServeurpersoCom marked this pull request as draft December 14, 2025 12:20

loci-dev mentioned this pull request Dec 14, 2025

UPSTREAM PR #18028: Webui/server config defaults auroralabs-loci/llama.cpp#564

Open

github-actions bot added examples server labels Dec 14, 2025

ServeurpersoCom marked this pull request as ready for review December 14, 2025 15:39

ggerganov reviewed Dec 14, 2025

View reviewed changes

common/common.h Outdated Show resolved Hide resolved

ggerganov reviewed Dec 14, 2025

View reviewed changes

allozaur approved these changes Dec 15, 2025

View reviewed changes

ggerganov approved these changes Dec 17, 2025

View reviewed changes

ngxson requested changes Dec 17, 2025

View reviewed changes

common/arg.cpp Outdated Show resolved Hide resolved

tools/server/server.cpp Outdated Show resolved Hide resolved

tools/server/server-models.cpp Outdated Show resolved Hide resolved

tools/server/server.cpp Outdated Show resolved Hide resolved

common/common.h Outdated Show resolved Hide resolved

ServeurpersoCom self-assigned this Dec 17, 2025

ngxson approved these changes Dec 17, 2025

View reviewed changes

tools/server/server.cpp Outdated Show resolved Hide resolved

ServeurpersoCom force-pushed the webui/server-config-defaults branch from 2977afc to f93fee0 Compare December 17, 2025 14:06

ServeurpersoCom added 2 commits December 17, 2025 15:12

server: address review feedback from ngxson

1ab2aa4

server: regenerate README with llama-gen-docs

bd9018b

ngxson merged commit 6ce3d85 into ggml-org:master Dec 17, 2025
65 of 72 checks passed

ServeurpersoCom mentioned this pull request Dec 18, 2025

Misc. bug: WebUI, first application of default settings (JSON) #18185

Closed

ServeurpersoCom mentioned this pull request Dec 20, 2025

webui: apply webui_settings on first load #18223

Merged

loci-dev mentioned this pull request Dec 20, 2025

UPSTREAM PR #18223: webui: apply webui_settings on first load auroralabs-loci/llama.cpp#637

Closed

Anri-Lombard mentioned this pull request Dec 29, 2025

Misc. bug: Unhandled exception for non-existing --models-dir #18037

Closed

Conversation

ServeurpersoCom commented Dec 14, 2025

server/webui: add CLI support for configuring WebUI defaults

Summary

Problem

The TODO that guided this implementation

Backend Changes (C++)

What was added

How it works

Frontend Changes (TypeScript)

What was added

Settings intentionally excluded

Priority Order

Usage Examples

Config file

Environment variable

Both (env var overrides file)

Check it works

Testing

Backend

Frontend

Backward Compatibility

What this enables

Uh oh!

ServeurpersoCom commented Dec 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

frontend.json

Uh oh!

ServeurpersoCom commented Dec 14, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

allozaur left a comment

Choose a reason for hiding this comment

Uh oh!

ggerganov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ngxson commented Dec 17, 2025

Uh oh!

ServeurpersoCom commented Dec 17, 2025

Uh oh!

ngxson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ServeurpersoCom commented Dec 17, 2025

Uh oh!

woof-dog commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jbone1313 commented Dec 18, 2025

Uh oh!

ServeurpersoCom commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ServeurpersoCom commented Dec 18, 2025

Uh oh!

jbone1313 commented Dec 18, 2025

Uh oh!

ServeurpersoCom commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jbone1313 commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ServeurpersoCom commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ServeurpersoCom commented Dec 14, 2025 •

edited

Loading

woof-dog commented Dec 17, 2025 •

edited

Loading

ServeurpersoCom commented Dec 18, 2025 •

edited

Loading

ServeurpersoCom commented Dec 18, 2025 •

edited

Loading

jbone1313 commented Dec 19, 2025 •

edited

Loading

ServeurpersoCom commented Dec 19, 2025 •

edited

Loading