> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/troubleshooting/install-and-runtime.md).

# Install & runtime

Fix RuntimeNotInstalled, a missing or undownloaded signed runtime, an unsupported platform, and native-kernel-not-found (TELYS\_KERNEL) errors.

The `telys` package is a thin, pure-Python SDK. Every collection operation runs inside the **signed native runtime**, which is downloaded and verified separately. Embedders such as `AlgentaBigramEmbedder` also need the **native kernel**. If either is missing, you'll see an error below.

{% hint style="info" %}
Confirm which layer is missing first: `telys version` proves the SDK is installed, `telys runtime status` exits `0` only when a verified runtime is ready, and constructing an `Algenta*` embedder proves the kernel loads.
{% endhint %}

## Quick check

```bash
telys version          # telys 0.1.15 (format v1)  — SDK only, no runtime needed
telys runtime status   # exit 0 = ready, exit 1 = not installed / not ready
```

## Errors and fixes

<details>

<summary><code>RuntimeNotInstalled</code> when you call any collection method</summary>

`Telys(...)` constructs fine — it loads the runtime lazily. The error fires the first time you touch the engine (`create_collection(...)`, `open_collection(...)`, or `add_texts(...)`), because the signed native runtime couldn't be loaded.

**Cause:** no signed runtime is installed under `$TELYS_HOME` (default `~/.telys`).

**Fix:** sign in to install the runtime, then confirm it's ready.

```bash
telys login            # free telys_developer; installs + verifies the runtime
telys runtime status   # expect exit 0
```

```python
from telys import Telys

mem = Telys("./memory")                 # OK even with no runtime
col = mem.create_collection(            # RuntimeNotInstalled fires here if the runtime is missing
    "notes", dim=384, partition_by="scope",
)
```

If `telys login` isn't an option (CI, air-gapped), install a runtime bundle from disk — see the next entry.

</details>

<details>

<summary>Runtime not downloaded (<code>telys runtime status</code> exits 1)</summary>

The SDK is installed but no runtime has been fetched yet.

**Cause:** you installed `telys` with pip or pipx but never ran `telys login` or `telys runtime install`.

**Fix (online):** download the signed runtime for your platform.

```bash
telys runtime install                 # latest signed runtime for this platform
telys runtime install --version 0.1.0 # pin a specific version
```

**Fix (offline / air-gapped):** install a bundle from disk. Fully supported; never touches the network. `--license` (a signed offline license file) is required with `--file`.

```bash
telys runtime install --file ./telys-runtime-linux-x86_64.bundle --license ./license.jwt
telys runtime status
```

After either path, always run `telys runtime verify` before you depend on it.

</details>

<details>

<summary>Platform not supported at install time</summary>

The installer resolves your platform tag as `<os>-<arch>` (for example `macos-arm64`, `linux-x86_64`) and refuses an unsupported target.

**Cause:** you're on a platform outside the supported set. Supported: `macos-arm64`, `linux-x86_64`, `linux-arm64` (experimental). Windows is supported via WSL2. Intel macOS is not yet supported.

**Fix:** run Telys on a supported platform, or use WSL2 on Windows. See the platform-specific page for details.

Next: [Platform-specific issues](https://docs.telys.ai/troubleshooting/platform-specific.md)

</details>

<details>

<summary>Native kernel not found when constructing an <code>Algenta*</code> embedder</summary>

Importing `AlgentaBigramEmbedder` works, but **constructing** it raises `ImportError`: it reads its dimension from the native kernel, and the kernel library couldn't be found.

**Cause:** the `libame_kernel` shared library isn't where Telys expects it. A verified `telys runtime install` places it under `~/.telys/runtime/<platform>/`, so this usually means no runtime is installed, or the path is non-standard.

**Fix:** install the runtime (it ships the kernel), or force the kernel path. `$TELYS_KERNEL` takes priority, then the legacy `$AME_KERNEL`.

```bash
telys runtime status                             # confirm the runtime (and kernel) are present

# Or force an explicit kernel library path:
export TELYS_KERNEL=/opt/telys/libame_kernel.so  # highest priority
export AME_KERNEL=/opt/telys/libame_kernel.so    # legacy fallback
```

```python
from telys.embedding import AlgentaBigramEmbedder

emb = AlgentaBigramEmbedder()   # reads its dim from the kernel; ImportError if unreachable
print(emb.profile.dimension)    # kernel-sourced (server hint: 64-d)
```

`AlgentaPooledEmbedder` and `HeuristicTuner` are **runtime-only**: they resolve lazily from the runtime and raise `ImportError` in a runtime-free install. Install the runtime to use them.

</details>

## Next steps

Once installed, confirm the runtime is trusted — a present-but-unverified runtime still fails closed.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Signature verification failures</strong></td><td>Confirm the runtime signature and license before you rely on it.</td><td><a href="https://docs.telys.ai/troubleshooting/signature-verification.md">Signature verification</a></td></tr><tr><td><strong>Verify your install</strong></td><td>The end-to-end check that everything is ready.</td><td><a href="https://docs.telys.ai/start-here/verify-install.md">Verify install</a></td></tr></tbody></table>

Next: [Signature verification failures](https://docs.telys.ai/troubleshooting/signature-verification.md)
