Run the Understand AI server (undaiserver)

Every local AI feature — AI Overviews, chat, AI code search, and Git-diff summaries — is served by undaiserver, a small local inference server that ships with Understand (the ai install kits). For normal use you never touch it: Understand starts it for you, shares one instance across all your windows, and stops it on exit. This page is for when you want to run, verify, or tune it yourself.

You usually don't need this

Just want AI on? Enable it on the Data page (see overview & setup) and Understand manages the server automatically. Read on only if you're troubleshooting, tuning hardware use, or running the server yourself.

How Understand manages it

When AI is enabled with the bundled Understand Local provider, Understand launches undaiserver listening on 127.0.0.1:56767 and talks to it over a local WebSocket. Because it binds 127.0.0.1, it is reachable only from your own machine. Multiple Understand windows share the same server, and closing Understand shuts it down.

The und ai command also uses the server — it generates AI overviews and the AI Code Search index from the command line, and its -server option can point at an already-running instance.

The executable sits in the Understand program directory next to und — e.g. C:\Program Files\SciTools\bin\pc-win64\undaiserver.exe on Windows, bin/linux64/undaiserver on Linux, and inside the app bundle on macOS.

Run it yourself

From that directory you can start the server by hand — useful when verifying an install or running it outside the GUI:

undaiserver --tcp 56767

A standalone server needs a model. The ai kits install a bundled GGUF under conf/understand/models/, which the server picks up automatically; otherwise point it at a model with --model-path (or the UNDAI_LLAMA_MODEL_PATH environment variable).

Check that it works

undaiserver --self-test

--self-test loads the model, runs a tiny inference, prints the active backend (Metal, CUDA, Vulkan, or CPU), the context size, and a sample of output, then exits. If it reports a GPU backend, acceleration is working; CPU means no supported GPU was found.

While a server is running you can also query it over HTTP:

• GET http://127.0.0.1:56767/healthz — liveness check.
• GET http://127.0.0.1:56767/api/status — queue depth and recent latency.

Stop it

undaiserver --quit

Common command-line options

Option	Purpose
-t, --tcp [PORT]	Listen on TCP (default port 56767).
-n, --network	Bind all interfaces (0.0.0.0) so other machines can connect. Requires --tcp. See Share one AI server across your team.
--self-test	Load the model, run one inference, print the backend, and exit.
-q, --quit	Tell a running server to shut down.
-v, --version	Print the server version.
--model-path <file>	Use a specific GGUF model.
--n-ctx <n>	Context window size (default 32768 tokens).
--n-gpu-layers <n>	Layers to offload to the GPU (-1 = all, 0 = CPU only).
--n-threads <n>	CPU threads.
--log-level <LEVEL>	DEBUG for verbose startup and runtime logging.

Anything set on the command line can also be set with an UNDAI_* environment variable — handy when running as a service (see Run the AI server as a background service). The most useful ones:

Variable	Equivalent
UNDAI_LLAMA_MODEL_PATH	--model-path
UNDAI_LLAMA_N_CTX	--n-ctx
UNDAI_LLAMA_N_GPU_LAYERS	--n-gpu-layers
UNDAI_SERVER_HOST / UNDAI_SERVER_PORT	--host / --tcp
UNDAI_LOG_LEVEL	--log-level

Hardware and backends

undaiserver auto-detects the best backend the bundled build supports: Metal on Apple Silicon, CUDA on NVIDIA GPUs (needs current drivers), Vulkan, or CPU. A GPU with ≥ 6 GiB of memory is recommended; --n-gpu-layers controls how much of the model is offloaded. On macOS, AI runs on Apple Silicon only — it is disabled on Intel Macs.

Speed and answer quality both come from the pairing of hardware and model, not hardware alone — a 1B-parameter model on a laptop GPU and a much larger model on a data-center-grade server will feel like entirely different tools. If you're running the server yourself with --model-path, see Choose a model for the size/VRAM/quality tradeoffs before picking one.

Logs and diagnostics

Runtime and startup logs are written to a per-user directory:

• Windows — %LOCALAPPDATA%\undai\undaiserver\logs
• macOS — ~/Library/Application Support/undai/undaiserver/logs
• Linux — ~/.local/share/undai/undaiserver/logs

A failed startup writes a startup_error_<timestamp>.txt there with the specific cause. For more detail, run with --log-level DEBUG. If a model won't load, see The AI model file failed to load.