KoboldCpp kcpps files: save, load and share your settings

What’s inside a KoboldCpp kcpps file

A .kcpps file is plain JSON with one key per setting, named after the flag’s internal name: contextsize, gpulayers, chatcompletionsadapter. Our 1.124.2 export has 160 keys, and most of them are at their default F05. This is a trimmed copy of our own export:

{
"model_param": "qwen2.5-0.5b-instruct-q4_k_m.gguf",
"contextsize": 4096,
"threads": 3,
"gpulayers": 10,
"batchsize": 512,
"quantkv": "f16",
"chatcompletionsadapter": "AutoGuess",
"port": 5001,
"istemplate": false,
…
}

Save your settings

In the launcher press Save Config. From the command line add --exportconfig to your usual flags: it writes the file and exits without loading a model, with exit code 0 F08. Keep the file next to the program so a shortcut can find it. There is no other place where KoboldCpp keeps settings, so to undo, delete the file.

Load a config: four ways

To load your settings every time, put the --config command in a shortcut (Windows) or a service (Linux). Or build and check one in the command builder.

Edit one by hand

Only the keys you want to change are needed. A file with just a model, a context size and a thread count loaded, and every other setting took its default F81. Two traps:

• Use the internal names. A file with "ctx-size": 3072 loaded without any message and the server ran at the default 16384, so the dashed spelling does nothing F81. The key for each flag is on the flag list.
• JSON is strict. No trailing commas, double quotes only, and a Windows path needs doubled backslashes (C:\\models\\x.gguf). The command builder checks a pasted file.

.kcppt templates: settings you can share

A .kcppt is the same file with the settings that belong to one machine reset. We exported the same command both ways and compared them F81:

Upstream also resets the Horde key and worker name, SSL, tensor split, memory-mapping and mlock options (read from the code; our command did not set these). To make a template use --exporttemplate or the launcher’s Extra tab. To use one, open it with Load Config or --config; model fields that are links are downloaded at launch to --downloaddir or the working folder. Ready-made templates are on Hugging Face; the launcher’s Get Help menu has Newbie Templates (we did not open them: no display).

Old config files and renamed settings

KoboldCpp translates old key names when it loads a file F81:

The full list of renamed flags is on the flag list. The same file loaded the same way on a Windows and a macOS machine F102. We could not run a real file written by a 1.95 program, so a file from a very old version may still fail: open it in the command builder to see what it flags.

Safety

A config file cannot run a command by itself. The onready setting, which runs a shell command after start-up, is blanked when it comes from a file unless KoboldCpp was started with --allow-config-onready (upstream; introduced in 1.90 and 1.116). Model fields in a template can point anywhere, so load templates only from sources you trust, and never share a .kcpps that holds a password.

Switching configs while running (admin mode)

With --admin and --admindir a folder of configs can be swapped without restarting, from KoboldAI Lite or the admin API. Settings such as the port, host, passwords and SSL never change on a swap (upstream; not tested). See remote access.