# 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](https://aws.github.io/aws-lc-rs/requirements/windows) 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](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/../../.github/workflows/knowledge-ci.yml) tests the core and APIs on Linux x86-64/ARM64, macOS ARM64/Intel, and Windows x86-64. The [release workflow](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/../../.github/workflows/knowledge-release.yml) builds the native binaries. Runner labels follow [GitHub's published matrix](https://docs.github.com/en/actions/reference/runners/github-hosted-runners). 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](https://openssl-library.org/news/vulnerabilities-3.6/) · [Rust OpenSSL build flags](https://docs.rs/openssl/latest/openssl/#manual)

```sh
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](https://tsok.org/knowledge/docs/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`. `doctor` reports 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_secs` limits 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. `/healthz` proves authenticated access to SQLite. `knowledge status` reports 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](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/docs/mcp-validation.md) · [Testing](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/docs/testing.md)
