Building OKLM
How to build the library, the tools and the tests, which options exist, and every environment variable OKLM reads at run time.
Status: maintained.
Requirements
- A C17 compiler with GNU attributes: GCC 9+ or clang 10+ (MinGW-w64 GCC for Windows builds).
- GNU make, pthreads, libm.
- nilorea-library sources. The Makefile looks in
external/nilorea-libraryfirst, then../../nilorea-library; passNILOREA_DIR=/pathotherwise. Only source files are used: nilorea does not need to be built or installed. - Optional: Allegro 5 with its font, ttf, primitives and image addons,
and X11 (
oklm-gui, media decoding; with its dialog addon too, the graphical tools open the system's file dialog, GTK 3 on Linux, and without it their paths are typed), OpenSSL (the server's and the client's TLS), Xvfb (make gui-test), cppcheck (make check), Doxygen (make doc), pandoc (make docs-html), dpkg-deb and patchelf (make deb,make appimage), wget (make appimage), NSIS (make installer-windows), Docker (make docker-build), clang-format 21.1.8 (make format,make format-check; Debian's orpip install clang-format==21.1.8), clang with libFuzzer (make fuzz), Python 3 with venv and network access (make test-public). - Nothing for the OpenCL backend at build time: it is always compiled,
and loads an OpenCL ICD loader (
libOpenCL.so.1,OpenCL.dll) at run time when one is installed. - Optional:
glslc(Debian'sglslcpackage, or shaderc) for the Vulkan backend, which compiles its shaders to SPIR-V at build time and loads the Vulkan loader (libvulkan.so.1,vulkan-1.dll) at run time; no Vulkan SDK or headers. Withoutglslcthe library is built without it (vulkan.md).
Targets
| Target | What it does |
|---|---|
make / make all |
library, apps, tests |
make test |
build and run every test binary |
make asan-test |
same with AddressSanitizer + UBSan (GPU drivers left out: a sanitizer build loads none unless named) |
make tsan-test |
same with ThreadSanitizer (GPU drivers left out) |
make wine-test |
the Windows build run under Wine (with Allegro's DLLs on
WINEPATH when it has them) |
make windows-deps |
download the Allegro project's MinGW-w64 release and dependency pack
into external/mingw (SHA-256 checked), and build OpenSSL
there from its source release (SHA-256 checked; a few minutes, once;
needs perl) |
make windows-dist |
the Windows executables and every DLL they need, stripped then
signed (Signing the Windows
files), the certificate, LICENSE and
NOTICE, in build/mingw/dist/oklm |
make windows |
the same folder as dist/windows |
make installer-windows |
dist/oklm-VERSION-setup.exe, an NSIS installer of
dist/windows and the HTML documentation, signed as its
files are (Packages) |
make deb |
dist/oklm_VERSION_amd64.deb: the programs, the
libraries they need and the HTML documentation under
/opt/oklm (Packages) |
make appimage |
dist/oklm-VERSION-x86_64.AppImage, one file with the
same content (Packages) |
make docker-build |
the .deb and the AppImage built in a Debian container,
named with its codename (Packages) |
make gui-test |
oklm-gui under Xvfb with the server test's tiny model:
one message, the window saved to
build/test_server/gui.png |
make asan-opencl |
the OpenCL tests under AddressSanitizer + UBSan, without leak reports (see opencl.md) |
make bench |
matmul micro-benchmark |
make test-public |
download the public model corpus and check against llama.cpp's files (network, Python) |
make fuzz / make fuzz-run |
libFuzzer targets of the file parsers (clang);
FUZZ_TIME seconds each |
make check |
cppcheck over src, apps,
tests (fails on findings) |
make doc |
Doxygen HTML in build/doc/html, warnings in
build/doc/doxygen_warnings.log |
make docs-html |
README.md and every page under docs/ as a
browsable HTML set in build/doc/docs-html
(tools/docs/make-html.sh: page list following index.md, per-page table of contents, offline
search, dark and light themes); needs pandoc, and with Python 3 fails on
a dead link or a missing anchor |
make docs-lint |
Markdown checks (tools/docs/lint.sh: whitespace,
Status: lines, links and their anchors, the README's quick
start, every environment variable in this page) and, with python3, the
interfaces against the sources (tools/docs/interfaces.py,
which builds and runs nothing): every option of the usage texts of
oklm and oklm-gui in a page, every route of
oklm serve in the table of server.md and every route of a
listening agent in that of agent-loop.md,
every slash command in a page, every tool of
packaging/gui-tools.txt in gui.md,
and the synopsis blocks of cli.md equal to the
usage text (python3 tools/docs/interfaces.py synopsis
rewrites them) |
make format |
clang-format every C file (nilorea's style) but the training
snippets of tests/security/corpus/; refuses a clang-format
other than 21.1.8, whose line breaks differ |
make format-check |
fails when a C file is not as make format writes it,
listing each place; CI runs it with clang-format 21.1.8 from PyPI |
make show-config |
detected options |
make clean / make distclean |
remove this mode's build / every build |
Each mode builds into its own directory (build/release,
build/asan, build/tsan), so instrumented and
plain objects are never linked together. Use BUILD= to keep
another compiler apart:
make CC=clang BUILD=build/clang test.
Options
| Option | Effect |
|---|---|
DEBUG=1 |
-O1 -g with AddressSanitizer + UBSan |
DEBUG=1 DEBUG_THREADS=1 |
ThreadSanitizer instead |
FORCE_NO_ALLEGRO=1 |
headless build even when Allegro 5 is installed |
FORCE_NO_OPENSSL=1 |
no TLS even when OpenSSL is installed |
FORCE_NO_VULKAN=1 |
no Vulkan backend even when glslc is installed |
GLSLC=path |
the shader compiler of the Vulkan backend (default
glslc) |
MINGW=1 |
cross-compile for Windows (links bcrypt and
ws2_32 for nilorea). Without external/mingw:
x86_64-w64-mingw32-gcc, statically, standalone
.exe files without media decoding or window. With it
(make windows-deps):
x86_64-w64-mingw32-gcc-posix (the Allegro release's
toolchain), Allegro linked dynamically, oklm-gui.exe built;
ship the DLLs (make windows-dist). With
external/mingw/openssl (built by
make windows-deps) the Windows build has TLS: the server's
https, the client's, and the downloads of oklm models pull,
the trusted roots read from the Windows certificate store |
WIN_SIGN=auto, 1 or 0 |
whether make windows-dist, make windows
and make installer-windows sign: when
osslsigncode and the key are on the machine (the default),
or failing without them, or never (Signing the Windows files) |
WIN_SIGN_FINGERPRINT=hex |
the SHA-256 the signing certificate must have (default: the one
README.md gives); empty accepts any key |
EXTRA_CFLAGS=... |
extra flags for every C file (used by make fuzz) |
NILOREA_DIR=path |
nilorea-library source tree |
Compiler flags for OKLM's own code:
-std=c17 -Wall -Wextra -Werror -pedantic -Wshadow -Wstrict-prototypes -Wmissing-prototypes -Wformat=2 -Wvla -fno-fast-math -ffp-contract=off.
The last two keep floating-point results reproducible: no reassociation,
and no implicit fused multiply-adds, so the reference quantizers match
ggml's bit for bit. SIMD kernels are compiled with per-function target
attributes, so the binary runs on any x86-64 and picks AVX2 at run
time.
nilorea sources are compiled with nilorea's own dialect
(-std=gnu17) and without -Werror, and their
headers are included with -isystem.
Packages
Four targets write installable files to dist/ (not in
the repository), from the files of packaging/. The version
is OKLM_VERSION_STRING of include/oklm/oklm.h,
or VERSION=... on the command line. No target here changes
it: make bump-version does (the patch number plus one, or
make bump-version VERSION=x.y.z; it writes the header and
the Doxyfile's PROJECT_NUMBER), and
make show-version prints it. A release is: bump, commit,
tag, build.
| Target | File | Needs |
|---|---|---|
make deb |
dist/oklm_VERSION_amd64.deb |
dpkg-deb, patchelf |
make appimage |
dist/oklm-VERSION-x86_64.AppImage |
patchelf, wget (appimagetool is downloaded once into
build/packaging) |
make installer-windows |
dist/oklm-VERSION-setup.exe |
MinGW-w64, NSIS (makensis, 3.08 or newer to sign);
make windows-deps first for the window and media decoding;
osslsigncode and the key to sign |
make docker-build |
dist/oklm_VERSION-CODENAME_amd64.deb,
dist/oklm-VERSION-CODENAME-x86_64.AppImage |
Docker |
make deb and make appimage build
oklm (and oklm-gui when Allegro 5 is there) in
build/package, apart from the other builds, with
PACKAGE=1: the executables carry the run path
$ORIGIN/../lib and find the libraries shipped beside them
without LD_LIBRARY_PATH, which the commands the agent
starts would otherwise inherit. packaging/bundle-libs.sh
copies every library the executables need except those of
packaging/excludelist.txt (glibc, the C++ runtime, OpenGL,
X11, fontconfig: the host's), and points a copied library that has a run
path of its own (libpulse) at its new directory. OpenCL and Vulkan are
loaded at run time and are not bundled. With pandoc, the HTML
documentation of make docs-html goes in.
- The
.debinstalls/opt/oklm(bin,lib,docs,LICENSE,NOTICE), linksoklmandoklm-guiin/usr/bin, and adds a menu entry for each graphical tool (OKLM, the launcher; OKLM Chat; OKLM Servers and the others ofpackaging/gui-tools.txt) and one for the documentation. ItsDependsare the packages of the build host that provide the libraries left to the system, plusfonts-dejavu-corefor the window;ocl-icd-libopencl1andlibvulkan1are recommended. - The AppImage opens the launcher
(
oklm-gui --tool launcher) when started without arguments, runsoklmwith its arguments otherwise, andoklm-guiwith arguments after--gui(packaging/AppRun); a link to it namedoklm-guiisoklm-gui. The launcher's Documentation button opens the HTML documentation bundled inusr/share/doc/oklm/html, from a copy that outlives the AppImage's mount, and a tool it starts is the AppImage again with--gui --tool NAME(gui.md). The windows load the DejaVu fonts of the host. - The menu entries of the graphical tools come from
one list,
packaging/gui-tools.txt: a line a tool (what--tooltakes, the desktop file's id, the name, the comment, the keywords), from whichpackaging/gui-menu.shwrites the.deb's desktop files, the AppImage's (the first line's) and the installer's Start Menu shortcuts. A new tool with a menu entry is one line there. - Both are tied to the system they are built on: the
executables need its glibc or a newer one, and the
.debnames its packages.make docker-build(packaging/docker-build.sh,packaging/Dockerfile) builds them in adebian:trixie-slimcontainer, for Debian 13 and newer;BASE_IMAGE=debian:bookworm-slim make docker-buildtargets an older release, where a missingglslcpackage leaves the Vulkan backend out. The sources are mounted read-only and copied withoutbuild/,models/anddata/; the container writes only the two files, owned by the caller.NILOREA_DIRnames nilorea-library when it is not at its usual place. - CI builds and publishes the three for a version tag
(
v*), and when its workflow is run by hand: the jobpackagesof.gitea/workflows/ci.ymlrunspackaging/ci-packages.shin adebian:trixiecontainer (the.deband the AppImage asmake docker-buildnames them, with the codename; the installer ofmake windows-deps installer-windows, signed when the repository has the two signing secrets and not signed without them;SHA256SUMS-VERSION). The files are the run's artifactoklm-packages, and for a tagpackaging/ci-release.shattaches them to the tag's release on the server, which it creates when there is none. The release is written with the repository's secretRELEASE_TOKENwhen it has one (a token that may write releases), else with the run's own token. - The Windows installer packs
dist/windows(make windows: the executables, their DLLs,NiloreaStudio.cerwhen the build signed them,LICENSE,NOTICE) and the HTML documentation. It installs toProgram Files\OKLMand adds Start Menu entries: the launcher and each graphical tool, the list of models to download, a command prompt withoklmon itsPATH, the documentation, the uninstaller. It does not change the systemPATH. Built aftermake windows-deps, it carries OpenSSL's two DLLs, which the model downloads need. The folder ofmake windowsruns from anywhere by itself (the programs find their DLLs beside them); it holds no documentation, which the installer adds asdocs-htmlbeside the programs, where the launcher's Documentation button looks fordocs-html\index.html. The graphical tools keep their state under%LOCALAPPDATA%\oklm(the background processes and their logs inprocs, the listening agents inagents, the models inmodels) and%APPDATA%\oklm(the profiles, the saved servers, the folders opened). The Windows build was run under Wine 11 only (gui.md,tools/check_gui_wine.sh): nothing was run on Windows itself. - Paths on Windows are UTF-8, as every text of OKLM
is. The Windows C runtime takes a
char*path, a command or a variable's name in the system's code page, which cannot name every file (a folder in Greek on a French system). The Windows build is compiled with-include src/core/win_utf8.h: before every source file, nilorea's included, that header names the runtime's functions that take such a text (fopen,open,stat,opendirandreaddir,rename,remove,mkdir,getcwd,_fullpath,getenv,putenv,system,popenand their neighbours) as the functions ofsrc/core/win_utf8.c, which convert from UTF-8 and call the wide one; no source file has an#ifdeffor it. The calls to the Windows API itself (CreateFile,MoveFileEx,CreateProcess,LoadLibrary...) go through the same file'soklm_w8_functions.oklm.exeandoklm-gui.exeread their arguments from the wide command line, split by the runtime's own rules (oklm_sys_utf8_args()), and set a console's output to UTF-8 while they run. A text that is not valid UTF-8 is read in the system's code page, as before. A new source file needs nothing; a new call to a narrow function of the Windows API that takes a path does (oklm_w8_wide()). Run under Wine 11: a model, a PDF, an index, a session and a screenshot inModèles Ελληνικά 日本語were read and written by both programs, where the build before answeredcannot open(testing.md). Not covered: a name longer than 255 bytes in UTF-8 (Wine cuts it on a Linux file system); nilorea's own calls that start a program or open a document (CreateProcessA,ShellExecuteAinn_common.c), which the windows no longer use on Windows (gui_self_spawn(),gui_open_path()) andoklm.exestill does for an address it opens in the browser; the window's font, which has no glyph for Chinese, Japanese or Korean (the name is right, drawn with gaps); a path longer thanMAX_PATH. - File sizes and offsets are 64 bits wide on Windows
too. MinGW's
struct statandoff_thold 32 bits unless_FILE_OFFSET_BITS=64is defined, which the Windows build does: every size read withstat()is right above 2 GiB (a model's file, an index, a job's output). A place in a file that can grow is anint64_tmoved to withoklm_file_seek(), never alonggiven tofseek():longis 32 bits wide there (src/harness/jobs.c, the followed files of the retrieval manager and ofoklm agent). - No package holds a model.
oklm modelslists what can be downloaded andoklm models pull NAMEinstalls it in the user's model directory (models.md).
Checked on 2026-11-12, with the menu entries of the graphical tools:
the .deb built here holds
net.nilorea.oklm.desktop (the launcher) and
net.nilorea.oklm.chat.desktop, both passing
desktop-file-validate; the AppImage started without an
argument under Xvfb opened the launcher, and
--gui --tool list, a link named oklm-gui and
--version answered as before; the installer run silently
under Wine made the shortcuts OKLM and OKLM Chat.
Checked on 2026-11-12: the trixie .deb installed in a
clean debian:trixie-slim container, where
oklm run generated from a GGUF file on the CPU and
oklm-gui found every library; the AppImage's
oklm ran there; the installer, run silently under Wine,
installed the files and the shortcuts and its oklm.exe
started. A .deb built on a newer system than the one it is
installed on fails to start (GLIBC_2.43 not found on Debian
13 for a build of this machine), which is what the container build is
for.
Signing the Windows files
A security product reported a small unsigned DLL of another
NiloreaStudio program, built with MinGW-w64 and carrying neither a
version resource nor a signature, as a known malware loader. OKLM's
Windows files had the same three marks: no resource in
oklm.exe and oklm-gui.exe, no signature
anywhere, and the debugging sections left in every file. Since 1.0.3 the
folder of make windows-dist is made in three steps, none of
which changes what a program does:
- A version resource.
oklm.exeandoklm-gui.exelinkpackaging/version.rc, compiled bywindresonce for each: company NiloreaStudio, product OKLM, the file's description and own name, the version ofinclude/oklm/oklm.h, the licence. Explorer shows them under Properties, Details. The DLLs of Allegro, OpenSSL and GCC are given none: they are other people's files, and a resource naming us on them would be false (OpenSSL's two andlibwinpthread-1.dllcarry their projects' own). The installer and its uninstaller name the company too, and so does the Publisher that Windows lists the installed program with. The test programs ofmake wine-test, which no package holds, have none. - No debugging sections. Every exe and DLL of the
folder is stripped (
strip --strip-unneeded): 47 MB where it held 121,oklm.exe13 MB for 29, the toolchain'slibstdc++-6.dll2.5 MB for 30. The programs inbuild/mingw/binkeep their symbols and are not signed; they are whatmake wine-testandtools/check_gui_wine.shrun. - A signature.
tools/windows_sign.shsigns every exe and DLL of the folder, the third-party ones included, andmake installer-windowssigns the installer and the uninstaller inside it, withosslsigncode(Debian:apt install osslsigncode). Signing a DLL we did not write says who shipped it, not who wrote it; a rule on the publisher has to hold for the whole folder. The signature is Authenticode, SHA-256, from a self-signed certificate named NiloreaStudio, the company name of the resources. It is made after the strip, which rewrites the file.
Why self-signed: a certificate from an authority costs money and an identity check, and its key has to live on a hardware token or in a signing service. A self-signed one proves nothing to a stranger: Windows shows it as not trusted and SmartScreen is not satisfied. What it gives is a publisher that stays the same from one build to the next, which an administrator can allow once where an exception by hash is redone at every build.
The key and the certificate are not in the tree. They are in
~/.config/nilorea/signing (key.pem,
cert.pem), or in the directory WINSIGN_DIR
names, shared with the other NiloreaStudio programs. The certificate
lasts ten years, can only sign code and cannot issue certificates.
key.pem has no passphrase and is the publisher: whoever has
it signs as NiloreaStudio. Back it up and never commit it.
A build never creates the key. A machine without one
would make its own and sign as a second NiloreaStudio, whose fingerprint
is not the one README.md gives, and nothing would say so.
To sign on another machine, copy the two files there by hand, into
~/.config/nilorea/signing, the directory and
key.pem readable by their owner alone
(chmod 700, chmod 600). To become a new
publisher on purpose:
sh tools/windows_sign.sh new-key
which refuses when the directory already holds a key, and prints the new certificate's fingerprint.
The fingerprint is pinned. The Makefile's
WIN_SIGN_FINGERPRINT is the SHA-256 of the certificate the
builds are signed with, the one of README.md. A build that
finds another key fails, in every mode, rather than sign as somebody
else. make ... WIN_SIGN_FINGERPRINT= (empty) signs with
whatever key is there; a new publisher changes the value in the Makefile
and in README.md.
WIN_SIGN |
When osslsigncode or the key is missing |
|---|---|
auto, the default |
the build goes on unsigned and says "NOTHING IS SIGNED" |
1 |
the build fails: what a release uses |
0 |
nothing is signed, tool and key or not |
The uninstaller is signed while the installer is
built. It exists as a file only then:
packaging/installer.nsi has makensis run the
script on it before packing it (!uninstfinalize, NSIS 3.08
or newer), which needs sh on the PATH of
makensis. Should that step fail on some machine,
WIN_SIGN=0 builds the installer without it, unsigned.
The script reads WINSIGN_DIR, WINSIGN_NAME
(the name in a new certificate, NiloreaStudio by default),
WINSIGN_FINGERPRINT and WINSIGN_PRODUCT (the
description in each signature), which the Makefile sets,
WINSIGN_TIMESTAMP and OSSLSIGNCODE (the tool's
path). No timestamp is asked for, since that is a request to somebody
else's server at every build; WINSIGN_TIMESTAMP set to an
RFC 3161 URL adds one. Without one a signature stops verifying when the
certificate expires.
The public half is written beside the programs as
NiloreaStudio.cer, and the installer installs it there (the
uninstaller removes it with the folder). README.md says how
a machine's administrator installs it and gives its SHA-256 fingerprint,
that of the key the builds of the release machine are signed with. A new
key means a new fingerprint there:
sha256sum dist/windows/NiloreaStudio.cer
To check a signature from Linux:
osslsigncode verify -CAfile ~/.config/nilorea/signing/cert.pem -in FILE
The installer CI attaches to a release is signed only when
the server has the key, which it has not unless somebody puts
it there. Without it packaging/ci-packages.sh builds with
WIN_SIGN=0: the programs carry the version resource and are
stripped, nothing is signed, and the signed installer is the one
make installer-windows WIN_SIGN=1 writes to
dist/ on the release machine.
To have CI sign, add two secrets to the repository on the server
(Settings, Actions, Secrets), each the whole text of a file of
~/.config/nilorea/signing, its BEGIN and
END lines included:
| Secret | Content |
|---|---|
WINSIGN_KEY_PEM |
key.pem |
WINSIGN_CERT_PEM |
cert.pem |
Nothing else changes: the job packages of
.gitea/workflows/ci.yml hands them to
packaging/ci-packages.sh, where
packaging/ci-winsign.sh writes them to a directory made for
the run, readable by its owner alone, outside the tree and outside the
job's artifact, removed when the script ends however it ends; it prints
neither. The build then runs with WIN_SIGN=1 and the pinned
fingerprint, so a pair that is not the publisher's, or a missing
osslsigncode, fails the job. One secret without the other
fails it too. Removing the two secrets goes back to unsigned
packages.
This is a decision with a cost. The key is then on the server and in
every run of that job: whoever administers the server or its runner, and
whoever may change the workflow or a script the job runs on a branch it
runs for (a tag v*, or a run started by hand), can sign any
file as NiloreaStudio, or copy the key out. The log masks a secret's
text but a script can still send it elsewhere. A key that leaked cannot
be called back: every machine that trusted the certificate has to remove
it. Keeping the key on the release machine and attaching the signed
installer built there costs a manual step and none of this.
Checked on 2026-11-18, on the cross build: the resource reads back
from both programs (1.0.3, their own names); no file of the
folder has a debugging section left; osslsigncode verify
succeeds on the 17 files and on the installer against the certificate,
and fails on a copy of oklm.exe with one byte changed; the
certificate's SHA-256 is the one in README.md; the
installer holds NiloreaStudio.cer; the stripped and signed
oklm.exe version answers under Wine; a second build relinks
nothing. With WIN_SIGN=0 the folder and the installer are
built unsigned, without the certificate and without a warning of
makensis. The uninstaller the installer wrote, installed
silently under Wine, verifies, and the Publisher read back there is
NiloreaStudio. The script's refusals were each seen once: no tool with
WIN_SIGN=1, no key with auto (unsigned, no
certificate written) and with 1, a throwaway key against
the pinned fingerprint, new-key over a key, a mode that is
none of the four, a directory holding one of the two files, a file that
is no program. The lines of ci-packages.sh that sign were
run here with a throwaway pair in the two variables: refused with the
pinned fingerprint, and with it emptied the 17 files, the uninstaller
and the installer signed by that pair, its directory gone after both
runs and neither text in the log; with no variable,
WIN_SIGN=0; with one, an error. Not checked: the job itself
on the server with real secrets, the signatures and the
certutil commands on a Windows machine, the static build
made without make windows-deps, and whether a security
product that matched such a file still does.
Environment variables
Every variable OKLM reads, grouped by area: what it does, its
default, and where it is read. This table is the one reference; other
pages name a variable only where they explain the behaviour it changes,
and link here. tools/docs/lint.sh checks that every
variable the sources read appears on this page. Values passed in
oklm_init_params, in a context's parameters or on the
command line take precedence over the environment.
Library: threads, SIMD, logging
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_THREADS |
CPU worker count, caller included | number of physical cores | src/oklm.c (oklm_init) |
OKLM_EXPERT_GPU_STREAM |
tokens from which a batch runs every pair on the device, the experts
the device expert tier does not hold copied through its staging slots
(0: never, the misses on the CPU) |
32 | src/model/expert_gpu.c |
OKLM_EXPERT_GPU_XFER |
0: the device expert tier's refills copy on the
device's queue instead of its transfer queue |
on | src/model/expert_gpu.c |
OKLM_CPU_FREE_CAP |
0: a CPU loop takes the whole team even when other
programs keep every core busy (by default, Linux: no more participants
than the cores left free, from /proc/stat's runnable
threads less this process's, sampled at most every 100 ms) |
on | src/core/cpu/team_cpu.c |
OKLM_MATVEC_THREADS |
threads at most of a one-row (decode) matrix product on a packed
copy, bound by memory, and on the file layout under 4 MiB of weights;
0: all of OKLM_THREADS (larger matrices on the
file layout: one per physical core, whatever this says) |
half the physical cores, at least 2 | src/core/cpu/backend_cpu.c |
OKLM_SIMD |
auto, scalar, avx2,
avx512: the CPU kernels' instruction set |
auto (best supported) |
src/oklm.c |
OKLM_LOG_LEVEL |
0-7 or ERR, WARNING, NOTICE,
INFO, DEBUG |
NOTICE (the tests: quiet unless set) |
src/oklm.c, tests/oklm_test.h |
OKLM_LOG_FILE |
log to this file instead of stderr | unset | src/oklm.c |
Backends and devices
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_BACKEND |
auto, cpu, opencl,
vulkan: what oklm_backend_select(NULL) and the
oklm commands use when --backend is not
given |
auto |
src/core/backend.c |
OKLM_BACKEND_ORDER |
comma-separated backend names (vulkan,opencl,cpu):
auto takes the first one available instead of the highest
priority (by default by priority: Vulkan on a GPU, then OpenCL, then the
CPU, see vulkan.md) |
unset | src/core/backend.c |
OKLM_CL_DEVICES |
comma-separated device indexes or name substrings: one backend
instance each (opencl, opencl1, ...); a device
may be listed twice (two independent instances, which is how the split
is tested on one GPU); a name matching nothing (none)
leaves no OpenCL device |
every discrete GPU; the integrated ones (sharing the host's memory) only when there is none | src/core/opencl/backend_cl.c |
OKLM_CL_DEVICE |
one device, as an index (as oklm devices and the log
list them) or a substring of the device or platform name, when
OKLM_CL_DEVICES is unset |
first GPU | src/core/opencl/backend_cl.c |
OKLM_OPENCL_LIB |
ICD loader to use instead of libOpenCL.so.1 /
OpenCL.dll; when set, the only one tried (empty: OpenCL
disabled); an ASan/TSan build tries none unless it is set |
the system's | src/core/opencl/cl_loader.c |
OKLM_VK_DEVICES |
comma-separated device indexes or name substrings (of the device or
driver name): one Vulkan backend instance each (vulkan,
vulkan1, ...), a device listed twice giving two;
all: every GPU, discrete ones first; a name matching
nothing (none) leaves no Vulkan device. A CPU
implementation (llvmpipe) only when named |
every discrete GPU; the integrated ones only when there is none | src/core/vulkan/vk_device.c |
OKLM_VK_DEVICE |
one Vulkan device, as an index (as the log lists them) or a
substring of the device or driver name, when
OKLM_VK_DEVICES is unset |
as above | src/core/vulkan/vk_device.c |
OKLM_VK_Q8 |
the Vulkan backend's 8-bit products (the CPU's results bit for bit,
vulkan.md): 1
every MATMUL and MATMUL_ID decode step their shaders can run (Q4_K,
Q5_K, Q6_K, Q8_0, Q4_0, Q5_0 weights), 0 none (the float
products) |
the shapes measured not slower: on AMD the K-quants from 1536 values and 4096 rows and the blocks of 32 there from two to eight columns, on Intel the K-quants at every shape (on the row shaders) and the blocks of 32 from 512 values and 512 rows; MATMUL_ID decode steps on AMD for experts of 512 rows or more (the K-quants from 1536 values), on Intel as MATMUL | src/core/vulkan/vk_ops_q8.c |
OKLM_VK_Q8_ROWS |
the layout of the Vulkan 8-bit products of Q4_K, Q5_K and Q6_K
weights (the same bits either way): 1 the row shaders (the
activations rounded once by q8k_round, then a weight row
per invocation, q8kr_<type>), 0
q8mv_<type> (and, on Intel, the K-quants back on the
float products unless OKLM_VK_Q8=1) |
the row shaders on Intel GPUs, q8mv_<type>
elsewhere |
src/core/vulkan/vk_ops_q8.c |
OKLM_VK_ATTN_ROWS |
16 or 32: the query rows per block of the
Vulkan prompt attention tiles (32 only up to heads of 128),
for tests and tuning |
16 for heads over 128, and on a discrete GPU for heads over 64; else 32 | src/core/vulkan/vk_ops_attention.c |
OKLM_VK_EW_FLAT |
0: the Vulkan element-wise shader indexes every op in
general (32-bit divisions per element) instead of by the element for
contiguous tensors of one shape and by row for rows at a constant stride
(the same bits either way) |
1 |
src/core/vulkan/vk_ops_ew.c |
OKLM_VK_REPLAY |
0: the Vulkan backend runs every decode step directly
instead of recording it once and replaying it |
1 |
src/core/vulkan/vk_runtime.c |
OKLM_VK_FUSE |
0: the Vulkan backend runs a MoE layer's routing
(softmax, expert choice, weights), its gate and up products with their
SwiGLU, and a residual branch's last product or MoE sum with the scale
and the add after it, op by op instead of as one dispatch each (the same
bits either way) |
1 |
src/core/vulkan/vk_runtime.c |
OKLM_VK_COOPMAT |
0: the Vulkan prompt products stay on the F32 tiles on
a device with cooperative matrices (read at each product) |
cooperative matrices where the device has them | src/core/vulkan/vk_ops_gemm.c |
OKLM_VK_WIDE |
the Vulkan prompt products that ask for their activations at F32's
precision (oklm_matmul_wide(): the blocks of the vision and
audio encoders) on a device with cooperative matrices, read at each
product (vulkan.md):
0 as any other product, the activations rounded to F16
(faster, the embeddings 2.6e-3 to 1.5e-2 from the CPU's);
f32 the F32 tiles |
F16 weights on the cooperative matrices with the activations as two F16 parts, the other weight types on the F32 tiles | src/core/vulkan/vk_ops_gemm.c |
OKLM_MM_DEVICE_ACT_BYTES |
a number of bytes: an image encoder at the image's own size (Qwen2-VL, Qwen2.5-VL) on a device finds no room for a picture whose activations need more, and encodes it on the CPU (the path a device without memory takes; for tests) | ||
OKLM_PASS_CUT |
0: a pass on a device is never cut
(oklm_backend_pass_yield() does nothing): an encoder's pass
holds its device from its first op to its last, and the passes of other
threads wait for all of it, as before 2026-11-14 (read at the first
pass; server.md) |
an encoder's pass lets the waiting passes in between its blocks | src/core/backend.c |
OKLM_MM_DEVICE_ENDS |
0: an encoder or a vocoder given a device keeps in host
memory what stands outside its blocks, as before 2026-11-14: a vision
encoder's patch embedding and projector, the two convolutions of
Whisper's and Ultravox's encoders and Ultravox's projector, a vocoder's
whole network (read when the device is given:
oklm_vision_use_backend(),
oklm_whisper_use_backend(),
oklm_audio_use_backend(),
oklm_vocoder_use_backend()); for tests and
measurements |
1 |
src/mm/mm_internal.h |
OKLM_VK_MOE_TILES |
0: the Vulkan indexed products of more pairs than
experts stay on the mvid_<type> shaders (F32);
1: all of them on the prompt products' tiles (read at each
product) |
the tiles from 16 pairs an expert on average | src/core/vulkan/vk_ops_moe.c |
OKLM_VK_GEMM_SG |
32 or 64: the subgroup size of the Vulkan
cooperative-matrix prompt products, where the device lets a pipeline
require it |
64, else 32 |
src/core/vulkan/vk_ops_gemm.c |
OKLM_VK_GEMM_SPLIT |
n: every Vulkan prompt product split over k into n parts
(1: none), for tests and tuning |
chosen by the tile count and k | src/core/vulkan/vk_ops_gemm.c |
OKLM_VK_GRAPHS |
recorded decode steps a Vulkan instance keeps, 1 to 64 (the least recently used replaced by a key seen before) | 16 | src/core/vulkan/vk_runtime.c |
OKLM_VK_XFER |
0: no transfer queue; the Vulkan backend's stream
uploads (weight streaming, the expert tier's refills) are plain
uploads |
on where the device has a copy engine or a second compute queue | src/core/vulkan/vk_device.c |
OKLM_VULKAN_LIB |
Vulkan loader to use instead of libvulkan.so.1 /
vulkan-1.dll; when set, the only one tried (empty: Vulkan
disabled); an ASan/TSan build tries none unless it is set |
the system's | src/core/vulkan/vk_loader.c |
OKLM_GPU_MAX_ALLOC_MB |
the largest device allocation, in MiB: the weights and the KV cache of a device are split into allocations of at most this size (to test the split on a small model) | the device's largest allocation | src/model/model.c |
OKLM_GPU_MEM_MB |
the device memory, in MiB, to assume when fitting layers, the server's KV blocks and the device expert tier (to test a smaller device, or share one) | the device's | src/model/model.c,
src/model/expert_gpu.c |
OKLM_STATE_KEEP |
states a context of a model with recurrent blocks
(qwen35, qwen35moe, qwen3next)
keeps so that a cut sequence starts again from the nearest one
(oklm_context_params::state_keep when that is 0), in host
memory whatever backend runs the blocks; 0: none, a cut
evaluates the prefix again |
8 | src/model/lin_keep.c |
OKLM_CL_GEMM_TILES |
64 x 64 output tiles from which matrix products of 32 columns or
more use the tiled kernels without splitting K (0: never,
1: always) |
256 | src/core/opencl/backend_cl.c |
OKLM_CL_GEMM_SPLIT |
largest number of K ranges for tiled products with fewer tiles than
that (1: no split, the row kernels instead) |
8 | src/core/opencl/backend_cl.c |
OKLM_CL_ATT_BLOCKS |
query blocks from which prompt attention uses the tiled kernels
without splitting the keys (0: never; a positive value:
every head size and span, 1: always); below that the keys
of each block are split when they span 8 tiles or more; an encoder's
bidirectional attention follows the same count on its own tiles
(0 also sends its windowed blocks,
oklm_attention_spans(), back to one launch a window) |
2 per compute unit, 4 for heads over 128, and only for the prompts
of OKLM_CL_ATT_KEYS |
src/core/opencl/backend_cl.c |
OKLM_CL_ATT_KEYS |
keys from which prompts with a float cache use the tiled attention
kernels by default (heads up to 128), and an encoder's bidirectional
attention its own (with a span of keys a query,
oklm_attention_spans(), whatever the keys' count) |
128 | src/core/opencl/backend_cl.c |
OKLM_CL_ATT_GQA |
0: the tiled attention kernels take one query head a
work-group, instead of the query heads that read one KV head
together |
on | src/core/opencl/backend_cl.c |
OKLM_CL_ATT_HALF |
0: F16 caches take the float-tile attention kernels
instead of the half-tile ones |
on | src/core/opencl/backend_cl.c |
OKLM_CL_WMMA |
on a gfx11 device (RDNA3). Unset: the tiled matrix products of
prompts with quantized weights that have no 8-bit kernel (the grid IQ
types, Q2_K, Q3_K, Q4_1, Q5_1, IQ4_NL, IQ4_XS, MXFP4, NVFP4, the ternary
and low-bit types) on the matrix units with F16 inputs
(wm_<type>, w2_<type>,
wi_<type> kernels, compiled as a second program at
the first product that takes them), the others as
OKLM_CL_Q8 says. 1 or f16: every
tiled product on them; bf16: with BF16 inputs.
0: none, the F32 kernels. Ignored on other devices (with a
notice when set) or when the compiler lacks the builtins |
the types without an 8-bit kernel (gfx11) | src/core/opencl/backend_cl.c |
OKLM_CL_WMMA_ATT |
0: with OKLM_CL_WMMA, the prompt attention
of F16 caches keeps the half-tile kernels
(attention_tile64h, attention_tile128h)
instead of the matrix units (attention_wm64h,
attention_wm128h) |
on (with OKLM_CL_WMMA) |
src/core/opencl/backend_cl.c |
OKLM_CL_Q8 |
0: quantized prompt products (Q4_K, Q5_K, Q6_K, Q8_0,
Q4_0, Q5_0 weights) on the F32 tile kernels instead of the 8-bit matrix
units of a gfx11 device (wq_<type>,
wqi_<type>: the activations rounded to 8 bits as the
CPU rounds them, the CPU's products bit for bit). Off with
OKLM_CL_WMMA set to 1, f16 or
bf16 |
on (gfx11) | src/core/opencl/backend_cl.c |
OKLM_CL_Q8_MV |
0: one-column products (decode, MoE decode steps) with
Q4_K, Q5_K or Q6_K weights on the float row kernels
(mv_<type>) instead of the 8-bit dot products
(mq_<type>: each work-group rounds its activation
column as the CPU rounds it, the CPU's products bit for bit; rows of
2048 values and more, 1024 rows and more). With OKLM_CL_Q8
on, and with OKLM_CL_WMMA (which leaves the prompt products
to the F16 / BF16 matrix units); OKLM_CL_Q8=0 turns both
off |
on (gfx11) | src/core/opencl/backend_cl.c |
OKLM_CL_Q8_COLS |
activation columns (rows of an indexed product) from which those products take the 8-bit kernels | 64 | src/core/opencl/backend_cl.c |
OKLM_CL_FUSE |
0: no fused launches (a MoE layer's routing, a layer's
query and key head norms with their rotation, a decode step's RMS norm
folded into the one-column product that reads it or run with the
rotation of its output (norm_fold), two copies in a row,
the end of a residual branch, a step's rotation with its cache writes;
each op then one launch) |
on | src/core/opencl/backend_cl.c |
OKLM_CL_MVG |
0: a MoE layer's gate and up products and their SwiGLU
as three decode launches instead of one (mvg_<type>,
mqg_<type>) |
on (with OKLM_CL_FUSE) |
src/core/opencl/backend_cl.c |
OKLM_CL_RES |
0: the end of a residual branch (the weighted sum of
the expert outputs, the add of the shared experts' output, the residual
scale, the add into the residual stream, the RMS norm of the sum that
follows) as two to five launches instead of one
(res_norm) |
on (with OKLM_CL_FUSE) |
src/core/opencl/backend_cl.c |
OKLM_CL_ROPE_KV |
0: a step's rotation of its queries and keys and the
writes of its keys and values into their caches as two to four launches
instead of one (rope_kv) |
on (with OKLM_CL_FUSE) |
src/core/opencl/backend_cl.c |
OKLM_CL_ROUTE_SIGMOID |
0: the routing of a MoE layer with a sigmoid router
(the sigmoid, the expert choice, the weights) as three launches instead
of one (moe_route, as a softmax router's) |
on (with OKLM_CL_FUSE) |
src/core/opencl/backend_cl.c |
OKLM_CL_ATT_MLA |
0: latent attention's prompts (heads of 257 to 576
dimensions, F16 cache) on the per-token kernel instead of the
latent-attention tiles |
on | src/core/opencl/backend_cl.c |
OKLM_CL_PROFILE |
1: time every kernel on the GPU (each launch waits for
the previous, so totals are exact but the run is slower) and print a
per-kernel table at exit; 2: host-side times only; the
OpenCL trainer too |
off | src/core/opencl/backend_cl.c,
src/train/train_cl.c |
Models and inference
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_TUNE |
0: contexts do not apply the cached work split of
oklm tune |
applied when cached | src/model/model.c |
XDG_CACHE_HOME |
base of the tuning cache ($XDG_CACHE_HOME/oklm/tuning),
of the expert cache's usage files
($XDG_CACHE_HOME/oklm/usage), of the copy of an AppImage's
HTML documentation the launcher opens
($XDG_CACHE_HOME/oklm/docs-html-VERSION) and of the
retrieval window's files ($XDG_CACHE_HOME/oklm/gui-rag: the
progress and the log of a build under way, the indexes of the
evaluations; %LOCALAPPDATA% on Windows) |
~/.cache |
src/model/tune.c,
src/model/expert_cache.c, apps/gui/shell.c,
apps/gui/tool_rag.c |
APPIMAGE, APPDIR |
set by an AppImage's runtime (its file, its mount): inside one, the launcher starts a tool from the AppImage's file rather than from the mount, and copies the documentation out of it before opening it | apps/gui/shell.c |
|
HOME |
the default of the paths above, and of the agent's user files (below) | src/model/, src/harness/,
apps/oklm.c |
|
USERPROFILE |
Windows, when HOME is not set: where the training
window's output goes by default (oklm-train under it) |
apps/gui/tool_train.c |
|
OKLM_CPU_PACK |
0: matrices are not repacked for the CPU kernels (the
file's layout used in place) |
repacked | src/model/model.c |
OKLM_CPU_PACK_EXPERTS |
0: the routed experts of a MoE model are never
repacked; 1: always (still not with an expert cache) |
repacked when the copies and the mapped experts fit in the available memory with the plan's margin, no expert cache | src/model/model.c |
OKLM_CPU_PACK_HUGE |
0: each repacked copy is an allocation of its own (4
KiB pages) instead of a slice of chunks aligned on 2 MiB and advised as
huge pages (Linux) |
chunks on huge pages (Linux) | src/core/cpu/pack_cpu.c |
OKLM_CPU_PROFILE |
1: wall time per CPU op (and per weight type for matrix
products), logged at shutdown |
off | src/core/cpu/backend_cpu.c |
OKLM_GELU_F16 |
1: the tanh GELU of the gated feed-forwards (Gemma,
Spark) rounds its input and its result to half precision, as ggml's
table of 65 536 values does; for the comparison with llama.cpp only |
off (single precision) | src/core/cpu/ops_cpu.c |
OKLM_ATTN_F16 |
1: attention over an F16 cache rounds each query to
half precision before the scores and each probability before the
weighted sum of the values, as ggml's matrix products with a
half-precision operand do (the path without flash attention); the plain
kernel then runs, several times slower; for the comparison with
llama.cpp only |
off (queries and probabilities in single precision) | src/core/cpu/attention_cpu.c |
OKLM_Q8_ROUND_EVEN |
1: the Q8_0 and Q8_1 activations of a matrix product
are quantized as ggml's x86 code does it (a value halfway between two
steps to the even one, the multiplier 127 / max) instead of ggml's
portable code, which OKLM follows on every machine (away from zero, 1 /
d); the two differ on exact halves only, which the first block of a
model with Q8_0 embeddings has; for the comparison with llama.cpp
only |
off | src/core/cpu/matmul_cpu.c |
OKLM_DUMP |
a file that receives every step of the llama family's forward pass
(the stream, the projections, the heads' outputs, the feed-forward's
parts, the logits), named as llama.cpp's graph names them, to be
compared with tools/llama_dump.c's by
tools/dump_compare.py (testing.md); host
memory only, one context |
none | src/model/dump.c |
OKLM_DUMP_FEED, OKLM_DUMP_FEED_OPS |
a dump of another program on the same tokens: every block starts
from that program's stream instead of its own, and with
OKLM_DUMP_FEED_OPS=1 the attention and each product inside
a block take that program's operands too, so that a difference is the
step's own |
none | src/model/dump.c |
OKLM_EMBED_GELU_TANH |
1: text encoders (bert) use the tanh GELU instead of
the exact one, as llama.cpp's bert does; for the comparison with
llama-embedding only |
off (exact GELU) | src/model/model.c |
OKLM_EMBED_TYPE0 |
1: pairs of texts (cross-encoders,
oklm_embed_pairs()) give every token type 0, as llama.cpp
does, instead of type 1 for the second text; for the comparison with
llama-embedding --pooling rank only |
off (the passage of type 1) | src/rag/embed.c |
OKLM_KV_ROTATION |
0: no rotation of keys and values in a quantized KV
cache |
on (head sizes that are multiples of 64, not MLA) | src/model/model.c |
OKLM_MOE_EXPERT_LOOP |
1: CPU MoE batches run one expert at a time instead of
the grouped products, for comparison (the same bits) |
off | src/model/model.c |
OKLM_FFMPEG |
1 (or a program path): videos in containers other than
Ogg Theora go through ffmpeg, as --ffmpeg |
off | src/mm/video.c |
TMPDIR, TEMP |
where a model with a --lora adapter merged in is
written while it loads, and where oklm agent commands makes
its scratch directory |
/tmp (. on Windows) |
apps/oklm.c |
PULSE_SOURCE |
the capture device PulseAudio's and PipeWire's client libraries
record: read when the chat window starts, set by its
Microphone chooser and by --mic NAME, and
put back when the system's default is chosen (gui.md) |
unset: the system's default input | apps/gui/tool_chat.c |
TMPDIR (TEMP, then TMP, on
Windows) |
where the chat window makes the folder of the temporary indexes of documents longer than the context (gui.md) | /tmp (. on Windows) |
apps/gui/chat_docs.h |
Server
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_KV_CHECK |
1: the scheduler checks the KV cache's block
bookkeeping after every step (tests) |
off | src/server/sched.c |
Trainer
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_TRAIN_LOGIT_ROWS |
rows of the logits held at a time by the chunked head (with
--recompute) |
about 2^26 floats, multiples of 64 rows | src/train/train.c |
OKLM_TRAIN_HEAD_ROWS |
vocabulary rows of a packed output head unpacked at a time when the whole head does not fit the scratch | the scratch's size | src/train/train.c |
OKLM_TRAIN_GD_HOST |
1: a device trainer runs the hybrid stacks' Gated DeltaNet blocks on the host (downloading and uploading), as heads larger than 128 do | 0: on the device | src/train/train.c |
OKLM_TRAIN_GRAD_TILE_ROWS |
vocabulary rows of the output head and token embeddings whose
gradients are computed at a time with BF16 gradients
(--grad-type bf16) |
as many as fit the largest block | src/train/train.c |
OKLM_HIP_LIB, OKLM_ROCBLAS_LIB |
the HIP and rocBLAS libraries of the rocm training
backend (empty: none); an ASan/TSan build tries none unless they are
set |
libamdhip64.so[.7], librocblas.so[.5],
then /opt/rocm/lib |
src/train/hip_loader.c |
OKLM_HIP_DEVICE |
the HIP device of the rocm backend, which must be the
OpenCL device's GPU |
0 | src/train/gemm_rocblas.c |
OKLM_ROCM_DEVICE_MB |
caps the device memory the rocm backend's
coarse-grained buffers take, in MiB; past it (or when the device is
full) buffers go to fine-grained shared virtual memory, which this
driver keeps in host memory |
0: until the device is full | src/train/train_cl.c |
OKLM_ROCM_MM16_MIN |
the smallest dimension (every one of M, N, K) from which `--matmul-precision bf16 | f16` runs a product in 16 bits; thinner products stay F32 | 128 |
OKLM_ROCM_W16_CACHE |
0: under `--matmul-precision bf16 |
f16`, no 16-bit copy of the weights kept between updates (2 bytes a parameter of device memory) and no rounding reused by the next product: every operand rounded at every product, as before 2026-11-08 (the same bits either way) | on when the copy fits with 512 MiB left on the device |
OKLM_ROCBLAS_MIN |
multiply-adds from which a product of the rocm backend
goes to rocBLAS |
2^22 | src/train/train_cl.c |
Agent
Settings read from the environment (the settings key in brackets; see
harness.md): OKLM_MODEL
(model), OKLM_SMALL_MODEL
(smallModel), OKLM_BASE_URL
(baseUrl), OKLM_OUTPUT_STYLE
(outputStyle), OKLM_BASH_TIMEOUT_MS
(bashTimeout), OKLM_MAX_TOOL_OUTPUT_CHARS and
BASH_MAX_OUTPUT (maxToolOutputChars),
OKLM_MAX_RETRIES (maxRetries),
OKLM_MAX_REASONING_TOKENS
(maxReasoningTokens), OKLM_COMMAND_CLASSIFIER
(commandClassifier); read in
src/harness/settings.c, they rank above the settings files
and below the command line and the managed settings.
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_MODELS_DIR |
the directory oklm models pull installs models in and
where catalogue names are resolved (models.md) |
$XDG_DATA_HOME/oklm/models, else
~/.local/share/oklm/models
(%LOCALAPPDATA%\oklm\models on Windows) |
src/client/models.c |
OKLM_MODELS |
directories (:-separated, ; on Windows)
where the agent looks for models |
./models, ~/.local/share/oklm/models |
apps/oklm.c |
XDG_DATA_HOME, LOCALAPPDATA |
base of the agent's model directory (oklm/models) |
~/.local/share |
apps/oklm.c |
OKLM_API_KEY, OPENAI_API_KEY |
the key oklm agent --url and
oklm chat --url send when --api-key is not
given (in that order) |
none | apps/oklm.c |
OKLM_DEBUG |
not 0: the agent's debug log, as
--debug |
off | apps/oklm.c |
XDG_STATE_HOME |
base of the debug log (oklm/logs) and of the logs of
the servers kept across logins (oklm/services);
LOCALAPPDATA on Windows, where it is also the base of the
listening agents' files (oklm\agents) and of the registry
of background processes (oklm\procs),
%USERPROFILE%\AppData\Local when it is not set |
~/.local/state |
apps/oklm.c, src/harness/kept.c |
OKLM_ENABLE_TELEMETRY |
not 0: the OpenTelemetry export, as
telemetry.enabled |
off | apps/oklm.c |
OTEL_EXPORTER_OTLP_ENDPOINT,
OTEL_EXPORTER_OTLP_HEADERS |
where the export goes and the headers it sends | telemetry.otlpEndpoint, none |
apps/oklm.c |
OKLM_MANAGED_SETTINGS |
the managed settings file instead of
/etc/oklm/managed-settings.json
(%ProgramData%\oklm\, macOS
/Library/Application Support/OKLM/) |
src/harness/settings.c,
src/harness/memory.c |
|
OKLM_MANAGED_MEMORY |
the managed memory file instead of the one in the managed directory | src/harness/memory.c |
|
OKLM_MCP_CREDENTIALS |
the MCP OAuth token file instead of
mcp-credentials.json beside the user's settings |
src/harness/oauth.c |
|
OKLM_DISABLE_BACKGROUND_TASKS |
set: the agent's commands cannot run in the background | allowed | src/harness/tools.c |
XDG_CONFIG_HOME, APPDATA,
USERPROFILE, ProgramData |
base of the user's settings, memory, skills, agents, plugins and
themes (oklm/) and, on Windows, of the managed files |
~/.config |
src/harness/, apps/oklm.c |
XDG_RUNTIME_DIR |
where the sandbox's network proxy socket goes, and whether a systemd
user manager can confine background jobs; base of the listening agents'
files (oklm/agents) and of the registry of background
processes (oklm/procs) |
the project's .oklm; ~/.cache for the
files |
apps/oklm.c, src/harness/jobs.c,
src/harness/listen.c,
src/harness/procreg.c |
LC_ALL |
read by the retrieval window before it opens the system's file
dialog, whose toolkit (GTK) takes the program's locale from the
environment: its value is moved to LANG and
LC_NUMERIC is set to C, so that numbers keep a
point for the decimals in the JSON the window and the commands it starts
write and read |
apps/gui/tool_rag.c |
|
OKLM_PROC_LOG |
set by the registry of background processes for the command it
starts, and by the unit of a server kept across logins: the file that
command's output goes to, which a program registering itself
(oklm serve) records as its log |
src/harness/procreg.c,
src/harness/kept.c |
|
OKLM_PROC_SERVICE |
set by the unit of a server kept across logins: the name it is kept under, which the server records in its entry of the registry | src/harness/kept.c,
src/harness/procreg.c |
|
OKLM_SYSTEMCTL |
a program run in place of systemctl for the servers
kept across logins (the tests put a script there; a wrapper can reach
the user manager from a session whose XDG_RUNTIME_DIR was
changed) |
systemctl on PATH |
src/harness/kept.c |
PATH |
where the programs the agent relies on are looked for
(systemd-run, clipboard tools) |
apps/oklm.c, src/harness/jobs.c |
|
TERMINAL |
the terminal emulator the sessions browser of oklm-gui
resumes a session in (started with -e and the command) |
x-terminal-emulator, then the usual ones |
apps/gui/tool_sessions.c |
VISUAL, EDITOR |
the editor the agent opens files in (memory files, definitions, the diff view) | vi |
apps/oklm.c |
WAYLAND_DISPLAY, DISPLAY |
which clipboard tool a copy to the clipboard tries
(wl-copy, xclip / xsel) |
apps/oklm.c |
|
NO_COLOR |
set and not empty: no colours in the terminal UI | colours on a terminal | src/harness/term_md.c |
GIT_CEILING_DIRECTORIES |
where the search for a project's git root stops | src/harness/git.c |
|
ANDROID_SERIAL |
the adb device; commands on a device that is not an emulator are flagged | src/harness/devices.c |
MCP server configurations may name other variables
(${VAR} in a command, an argument or a header), read when
the server starts (src/harness/mcp.c). The agent sets
OKLM_SESSION_ID, OKLM_PROCESS_ID,
OKLM_PROJECT_DIR and OKLM_DEBUG_LOG for the
commands, hooks and services it runs.
Tests
| Variable | Effect | Default | Read in |
|---|---|---|---|
OKLM_CL_DEVICES |
none runs the suite on the CPU alone (another program
may own the GPU) |
every GPU | tests/model/test_multi_device.c and the backend |
OKLM_VK_DEVICES |
the Vulkan tests (tests/core/test_vulkan*.c) set
all unless it or OKLM_VK_DEVICE is set;
none skips them |
every GPU | tests/core/vk_test_util.h and the backend |
OKLM_TEST_ONLY |
comma-separated words: a test binary runs only the test functions
whose names contain one
(OKLM_TEST_ONLY=test_vulkan,test_expert_gpu) |
every test | tests/oklm_test.h |
OKLM_UPDATE_SNAPSHOTS |
set: the prompt and memory snapshot tests rewrite their reference files | compare | tests/harness/test_prompt.c,
tests/harness/test_memory.c |
OKLM_MM_DUMP |
set: the multimodal tests write their preprocessed inputs as references | off | tests/mm/test_mm_public.c |
OKLM_FFMPEG |
unset: the video test skips the ffmpeg cases | tests/mm/test_video.c |