Platforms and processors
knowledge has a portable Rust/SQLite core and optional native inference. The app does not require Apple hardware or a GPU. Native model files, SQLCipher, media decoders and accelerators each have their own platform/toolchain requirements.
Build modes
| Mode | Command | Requirements |
|---|---|---|
| CPU with native models | python3 scripts/build.py --backend cpu |
Rust, C/C++ compiler, CMake, libclang, Perl for vendored OpenSSL |
| Apple Metal | python3 scripts/build.py --backend metal |
macOS, Xcode and Metal toolchain |
| NVIDIA CUDA | python3 scripts/build.py --backend cuda |
Compatible NVIDIA GPU, driver and CUDA development toolkit |
| Vulkan | python3 scripts/build.py --backend vulkan |
Vulkan development SDK, driver and compatible GPU |
| HTTP models | python3 scripts/build.py --backend http |
Rust/C compiler and SQLCipher/OpenSSL build prerequisites; no llama.cpp |
| Minimal CLI/library | cargo build --release --no-default-features |
Rust and C compiler for bundled SQLite; no encrypted DB or server |
The first four modes include raw multimodal support. CPU configs must set both models.embedding.gguf.gpu_layers: 0 and models.generation.gpu_layers: 0. A binary built without GPU features does not gain acceleration from a positive layer count. Select one accelerator for a deployment and match the installed toolchain. knowledge models reports compiled backend features and the selected model roles without loading weights.
Windows uses the MSVC toolchain (Developer PowerShell), CMake, LLVM/libclang and Perl for the vendored OpenSSL build. On Windows x86-64, the JWT backend uses NASM or the versioned assembly objects supplied by AWS-LC when AWS_LC_SYS_PREBUILT_NASM=1 is set. AWS-LC Windows build requirements Run python scripts/build.py --backend cpu, add the workspace release directory to Path, then run knowledge --validate-config. On Linux install a C/C++ compiler, CMake, libclang and Perl. On macOS install Xcode command-line/Metal tools as appropriate. The existing scripts/build-mac.sh remains a convenient M3 helper.
FFmpeg/ffprobe are needed only when video/GIF processing is enabled. Poppler's pdfinfo/pdftotext/pdftoppm are needed for PDFs; rasterization additionally needs fonts. Configure executable paths when tools are not on PATH. Nothing installs or launches model servers/decoders automatically.
After a source build, add the workspace release directory to PATH or install the binary in an existing PATH directory. A local CARGO_TARGET_DIR override changes the build output location. Use knowledge --version to verify which binary your shell resolves.
What has been verified
Actual execution in this workspace: Apple M3 ARM64, macOS, including native Metal embeddings/generation, a CPU-only native build with a real 768D embedding probe, a minimal core build, YAML, HTTP/TLS, SQLCipher and FFmpeg/Poppler integration. CUDA, Vulkan, Linux, Windows, Intel macOS and other ARM64 hosts have not been executed here. An Intel macOS core/API/SQLCipher cross-compile check passed; that is compile evidence, not Intel runtime execution.
The Knowledge CI matrix tests the core and APIs on Linux x86-64/ARM64, macOS ARM64/Intel, and Windows x86-64. The release workflow builds the native binaries. Runner labels follow GitHub's published matrix. Model downloads are excluded from routine CI; hardware/model tests run explicitly. CUDA/Vulkan require separate suitable runners.
Build each OS/architecture separately. Do not copy an ARM64 macOS executable to an Intel/Linux/Windows machine. GGUF files are runtime data and can be shared where the runtime supports their model architecture. Avoid -C target-cpu=native for distributable binaries targeting older CPUs; the pinned native build disables GGML_NATIVE unless explicitly requested upstream.
SQLCipher keys and TLS/API credentials must be provisioned per deployment. Unix mode-0600 checks do not enforce Windows ACLs: secure the source/key/state directories with appropriate account ACLs on Windows. GPU unified/discrete memory, swap and runtime native libraries are outside SQLite encryption. Treat external decoders and native inference dependencies as trusted software and keep them updated.
The build helper explicitly sets GGML_METAL for the selected backend because llama.cpp defaults Metal on for Apple hosts. CPU mode also disables context KQV/operation offload when gpu_layers is zero. If reusing an old native build cache configured outside the helper, clean that generated dependency once with cargo clean --release -p llama-cpp-sys-2 before rebuilding; the pinned CMake wrapper can otherwise reuse prior native options.
Production deployment
Build against the maintained OpenSSL installation for your target host. The build helper can select it for SQLCipher, and OPENSSL_DIR can identify an explicit installation prefix. The vendored dependency currently resolves to OpenSSL 3.6.3. The upstream 3.6 branch received security fixes in 3.6.5. Distribution-maintained packages may carry equivalent backports under their own version numbers. Knowledge uses rustls for inbound TLS. OpenSSL 3.6 advisories · Rust OpenSSL build flags
python3 scripts/build.py --backend http --system-openssl
knowledge --config /etc/knowledge/knowledge.yml check-server
knowledge --config /etc/knowledge/knowledge.yml doctor
knowledge --config /etc/knowledge/knowledge.yml serve
- Run as a dedicated service account. Grant read access to the configuration, keys, models and OKF source. Give the account write access to the SQLite state directory and to the OKF source only for deployments that allow authoring. Grant separate read-only access for enrolled database projections, dedicated manifest asset directories, or bucket prefixes. See connected sources.
- Provision a certificate and client trust from the deployment PKI. Keep authentication, database, and MCP keys in separate private files. Validate the actual certificate chain and hostname using an authenticated HTTPS probe to
/healthz.doctorreports the loaded SQLCipher provider and version for an encrypted database. - Give the supervisor time for the configured HTTP grace period and for active native inference or indexing to reach a safe boundary. Unix SIGTERM stops admission and starts HTTP shutdown.
server.transport.shutdown_grace_secslimits the HTTP drain. Keep the supervisor’s hard stop deadline separate. - If a proxy fronts the listener, forward Host, Origin and MCP routing headers, and allow request-scoped SSE to stream. Set proxy timeouts and connection limits to match your deployment's capacity. Use end-to-end TLS across an untrusted link.
- Check database readiness and job backlog separately.
/healthzproves authenticated access to SQLite.knowledge statusreports indexing state. Exercise backup and restoration to a separate database and OKF directory with the deployment key, then check integrity and a known citation before accepting traffic.
Before tagging a release, qualify the actual identity provider and client hosts, run the supported platform matrix, and review the upstream MCP conformance failures against the product's protocol surface. MCP validation · Testing