Installation¶
Get a telha binary
Telha ships as one binary, telha, containing both the server (telha serve) and the operator CLI. This page gets a binary onto your machine and verifies it runs; the quickstart takes it from there to a grounded, verified answer.
Full production detail lives in the runbook
This page covers dev/eval installation. Systemd deployment, backups, retention, upgrades, and the full key/secret inventory are in the deployment runbook.
Prerequisites¶
Nothing beyond the binary itself, for the ways to get it below. The build- from-source path needs a Rust toolchain; on Windows it specifically needs the GNU toolchain (not MSVC).
Three ways to get a binary¶
1. Windows dev/eval zip¶
Dev/eval only, not a production target. telha.exe is built with the GNU toolchain, which needs MinGW runtime DLLs (libstdc++-6.dll, libgcc_s_seh-1.dll, libwinpthread-1.dll) at runtime. The zip bundles that DLL closure next to the exe, so it runs on a clean Windows machine with nothing else installed.
Extract the zip anywhere and run telha.exe directly; a README.txt inside walks version check → API key → serve → curl probes.
Exit 127 without the bundled DLLs
A bare telha.exe, copied out of the zip or built locally without the MinGW runtime on PATH, dies instantly with exit code 127 (STATUS_DLL_NOT_FOUND) and no useful error message. Either run it from inside the zip's directory (the Windows loader prefers the application directory and finds the bundled DLLs there), or add C:\msys64\mingw64\bin to PATH if you have MSYS2 installed.
To build the zip yourself (or verify a release build):
# needs a release build first: core-engine\run-release-build.cmd
powershell -File tooling\packaging\make-windows-zip.ps1 -Verify
-Verify runs the staged exe with PATH stripped down to C:\Windows\System32;C:\Windows, proving the bundled DLL closure is actually sufficient. manifest.json inside the zip records the exact DLLs shipped.
2. Docker¶
Build the image from the repo root (the Dockerfile expects proto/ and core-engine/ alongside it):
The image is Debian bookworm-slim, runs as a non-root user (telha, uid 10001), declares a state volume at /var/lib/telha, exposes 7625 (REST), 7626 (gRPC), and 7627 (MCP), and has a built-in HEALTHCHECK against /readyz. ENTRYPOINT is telha, default CMD is serve.
docker run -d --name telha \
-p 7625:7625 -p 7626:7626 \
-v telha-data:/var/lib/telha \
-e TELHA_GRPC__TOKEN_KEY=<64-hex-with-a-letter> \
telha-core
curl -fsS http://127.0.0.1:7625/readyz # -> ok
docker-compose.yml at the repo root brings up core plus PostgreSQL and Redis (the app layer's stores) in one shot: docker compose up.
3. Build from source¶
Windows needs the GNU toolchain
On Windows, building core-engine requires the GNU Rust toolchain (not the default MSVC one) plus MSYS2 on PATH, because the engine links RocksDB's C++ code. If your Rust install defaults to MSVC, add and select the GNU target:
You'll also need LIBCLANG_PATH pointed at your MSYS2 install and C:\msys64\mingw64\bin on PATH for the build itself to find the MinGW toolchain (separately from the runtime-DLL requirement above, which only affects running the resulting exe outside its build directory or the zip).
The resulting binary is a plain build, not the DLL-bundled zip: on Windows with the GNU toolchain, run it from a shell that already has C:\msys64\mingw64\bin on PATH, or package it with make-windows-zip.ps1 first.
Verify it¶
If this exits instantly with no output on Windows, see the exit-127 note above: the MinGW DLLs are not reachable from wherever the exe is running.
Where data lives¶
Everything Telha stores lives under one directory you choose with --data-dir (or data_dir in a config file): the RocksDB storage engine's files, vector partitions, and api_keys.json, the file holding hashed API key credentials. The server loads api_keys.json at startup, so a key minted with telha api-key create only takes effect after the next serve start (or if minted before the first start).
Operator CLI subcommands that open the data directory directly (api-key create, backup create, retention, jobs, ...) need the server stopped first; they conflict with a running server's exclusive lock on the same directory.
Next steps¶
- Quickstart - mint an API key,
serve, ingest, query, time-travel, and generate a verified answer, in about ten minutes. - Deployment runbook - systemd deployment, the full key and secret inventory, backups, retention, and upgrades.