> 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

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.0b2 (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.

```bash
telys runtime install --file ./telys-runtime-linux-x86_64.bundle
telys runtime install --file ./telys-runtime.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](/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="/pages/0eykLEyLKnupmpNlVgH9">/pages/0eykLEyLKnupmpNlVgH9</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="/pages/h4z9ZPSmvEnW3qsGotXt">/pages/h4z9ZPSmvEnW3qsGotXt</a></td></tr></tbody></table>

Next: [Signature verification failures](/troubleshooting/signature-verification.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/troubleshooting/install-and-runtime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.