# Get started

## Use a release binary

Select the archive for your operating system and CPU in [GitHub Releases](https://github.com/tsok-org/source-code/releases?q=knowledge-v). Downloads follow the source repository's access policy. Check the archive against `SHA256SUMS`, then extract it. Add the extracted directory to your `PATH` and run the commands from that directory. The Windows archive contains `knowledge.exe`, which also runs as `knowledge` on `PATH`.

```sh
knowledge -c configs/reference.yml init-security
knowledge -c configs/reference.yml check-server
knowledge -c configs/reference.yml index
knowledge -c configs/reference.yml search "sensor calibration" --mode lexical
knowledge -c configs/reference.yml serve
```

The reference profile uses the included OKF example, encrypted SQLite, and read-only HTTPS and MCP. Select an encoder in the YAML when you want vector search. [Reference YAML](https://tsok.org/knowledge/knowledge.yml)

## Build from source

In the monorepo, work from `apps/knowledge`. After building, install the binary into a directory on your `PATH`, or add the workspace’s `target/release` directory to `PATH` for this shell.

Start with [knowledge.yml](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/knowledge.yml), which targets the original [sample OKF folder](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/examples/bundle/index.md). Read [configuration](https://tsok.org/knowledge/docs/configuration/) before changing paths or model roles.

```sh
python3 scripts/fetch-model.py
python3 scripts/build.py --backend metal # Apple silicon. Use cpu on CPU-only hosts.
export PATH="$(cd ../.. && pwd)/target/release:$PATH"
knowledge --validate-config
# Run once per local profile.
knowledge init-security
knowledge index
knowledge models
knowledge search "sensor calibration" --mode hybrid --rerank mmr
knowledge serve
```

The fetch script explicitly downloads the sample models. No startup action silently downloads weights. Default inference uses EmbeddingGemma 2 and its projector for vectors and Qwen2.5 1.5B Instruct for answers. Transcription and image-to-text are separate optional roles, not outputs of the embedding model.

CPU deployments must set `gpu_layers: 0` for both native model roles; build with `--backend cpu`. HTTP-only deployments use `--backend http` and configure compatible model servers. On Windows, run the Python build helper in Developer PowerShell and add the workspace’s `target\release` directory to `Path`. See [deployment](https://tsok.org/knowledge/docs/deployment/).

`init-security` refuses existing credentials. It creates private, independent database/API secrets, TLS material and derived YAML/JSON configs. Keep source, state and keys on protected storage. On another knowledge base use another config, database, credentials and API port. Explicitly opt into URL origins, HTTP model policies and source writes. Initialization preserves selected model roles and server settings while provisioning fresh TLS/credentials.

`serve` binds `https://localhost:8443` by default and starts the folder watcher/worker. Use the generated local CA and bearer credential; [security](https://tsok.org/knowledge/docs/security/) shows clients. No service is installed by setup. `watch` runs ingestion without HTTP; `index` scans and drains currently available jobs once. Failed jobs remain visible in `status`; correct the error and use `retry`/`work` or the watcher.

To try the additional media fixture, install FFmpeg and Poppler, then initialize the separate profile once:

```sh
knowledge -c configs/formats.yml init-security --output .knowledge-formats
knowledge -c configs/formats.yml index
knowledge -c configs/formats.yml search "a blue circle" --mode vector --representation native_video_frame
```

The fixture folder, policies and results are documented in [formats](https://tsok.org/knowledge/docs/formats/) and [the evidence report](https://github.com/tsok-org/source-code/blob/main/apps/knowledge/reports/formats/VALIDATION.md). The sample config expects decoder executables on PATH; set their paths when necessary.
