OKLMdocumentation v1.0.3
On this page

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-library first, then ../../nilorea-library; pass NILOREA_DIR=/path otherwise. 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 or pip 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's glslc package, 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. Without glslc the 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 .deb installs /opt/oklm (bin, lib, docs, LICENSE, NOTICE), links oklm and oklm-gui in /usr/bin, and adds a menu entry for each graphical tool (OKLM, the launcher; OKLM Chat; OKLM Servers and the others of packaging/gui-tools.txt) and one for the documentation. Its Depends are the packages of the build host that provide the libraries left to the system, plus fonts-dejavu-core for the window; ocl-icd-libopencl1 and libvulkan1 are recommended.
  • The AppImage opens the launcher (oklm-gui --tool launcher) when started without arguments, runs oklm with its arguments otherwise, and oklm-gui with arguments after --gui (packaging/AppRun); a link to it named oklm-gui is oklm-gui. The launcher's Documentation button opens the HTML documentation bundled in usr/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 --tool takes, the desktop file's id, the name, the comment, the keywords), from which packaging/gui-menu.sh writes 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 .deb names its packages. make docker-build (packaging/docker-build.sh, packaging/Dockerfile) builds them in a debian:trixie-slim container, for Debian 13 and newer; BASE_IMAGE=debian:bookworm-slim make docker-build targets an older release, where a missing glslc package leaves the Vulkan backend out. The sources are mounted read-only and copied without build/, models/ and data/; the container writes only the two files, owned by the caller. NILOREA_DIR names 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 job packages of .gitea/workflows/ci.yml runs packaging/ci-packages.sh in a debian:trixie container (the .deb and the AppImage as make docker-build names them, with the codename; the installer of make 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 artifact oklm-packages, and for a tag packaging/ci-release.sh attaches them to the tag's release on the server, which it creates when there is none. The release is written with the repository's secret RELEASE_TOKEN when 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.cer when the build signed them, LICENSE, NOTICE) and the HTML documentation. It installs to Program Files\OKLM and adds Start Menu entries: the launcher and each graphical tool, the list of models to download, a command prompt with oklm on its PATH, the documentation, the uninstaller. It does not change the system PATH. Built after make windows-deps, it carries OpenSSL's two DLLs, which the model downloads need. The folder of make windows runs from anywhere by itself (the programs find their DLLs beside them); it holds no documentation, which the installer adds as docs-html beside the programs, where the launcher's Documentation button looks for docs-html\index.html. The graphical tools keep their state under %LOCALAPPDATA%\oklm (the background processes and their logs in procs, the listening agents in agents, the models in models) 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, opendir and readdir, rename, remove, mkdir, getcwd, _fullpath, getenv, putenv, system, popen and their neighbours) as the functions of src/core/win_utf8.c, which convert from UTF-8 and call the wide one; no source file has an #ifdef for it. The calls to the Windows API itself (CreateFile, MoveFileEx, CreateProcess, LoadLibrary ...) go through the same file's oklm_w8_ functions. oklm.exe and oklm-gui.exe read 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 in Modèles Ελληνικά 日本語 were read and written by both programs, where the build before answered cannot 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, ShellExecuteA in n_common.c), which the windows no longer use on Windows (gui_self_spawn(), gui_open_path()) and oklm.exe still 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 than MAX_PATH.
  • File sizes and offsets are 64 bits wide on Windows too. MinGW's struct stat and off_t hold 32 bits unless _FILE_OFFSET_BITS=64 is defined, which the Windows build does: every size read with stat() is right above 2 GiB (a model's file, an index, a job's output). A place in a file that can grow is an int64_t moved to with oklm_file_seek(), never a long given to fseek(): long is 32 bits wide there (src/harness/jobs.c, the followed files of the retrieval manager and of oklm agent).
  • No package holds a model. oklm models lists what can be downloaded and oklm models pull NAME installs 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.exe and oklm-gui.exe link packaging/version.rc, compiled by windres once for each: company NiloreaStudio, product OKLM, the file's description and own name, the version of include/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 and libwinpthread-1.dll carry 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 of make 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.exe 13 MB for 29, the toolchain's libstdc++-6.dll 2.5 MB for 30. The programs in build/mingw/bin keep their symbols and are not signed; they are what make wine-test and tools/check_gui_wine.sh run.
  • A signature. tools/windows_sign.sh signs every exe and DLL of the folder, the third-party ones included, and make installer-windows signs the installer and the uninstaller inside it, with osslsigncode (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