> 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/reference/runtime-api.md).

# Runtime

Every collection operation runs inside the signed native runtime. Use `telys.runtime` to load and probe it. The runtime is not part of this package.

```python
from telys.runtime import load_runtime, runtime_available, RuntimeHandle, RuntimeNotInstalled
from telys import FORMAT_VERSION
```

## Functions

| Signature             | Returns         | Description                                                                                |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------ |
| `load_runtime()`      | `RuntimeHandle` | Load and return the active runtime. Raises `RuntimeNotInstalled` if it cannot be imported. |
| `runtime_available()` | `bool`          | `True` if a runtime can be loaded, without raising.                                        |

### load\_runtime()

The `TELYS_RUNTIME` environment variable selects the runtime:

| `TELYS_RUNTIME`      | Runtime loaded                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `"native"`           | The signed native runtime.                                                                 |
| `"local"`            | The local runtime.                                                                         |
| `""` (default, auto) | Native when a **verified** install is present (native-only, fail-closed); otherwise local. |

If the selection cannot be imported, `load_runtime()` raises `RuntimeNotInstalled`.

```python
from telys.runtime import load_runtime, runtime_available, RuntimeNotInstalled

if runtime_available():
    rt = load_runtime()
else:
    print("Install the runtime: telys runtime install")

try:
    rt = load_runtime()
except RuntimeNotInstalled:
    ...  # guide the user to install + verify
```

{% hint style="info" %}
You rarely call `load_runtime()` yourself — `Telys(...)` loads the runtime lazily on the first collection operation. Use these functions for capability checks and diagnostics.
{% endhint %}

## RuntimeHandle

The stable interface the SDK programs against; the signed runtime supplies the implementations. You don't instantiate it — `load_runtime()` returns the concrete handle for the selected runtime.

## Constants

| Constant               | Value | Meaning                                                                                        |
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------- |
| `telys.FORMAT_VERSION` | `1`   | On-disk format contract for saved collections. Also exposed as `telys.runtime.FORMAT_VERSION`. |

## Exceptions

| Exception             | Raised when                                          |
| --------------------- | ---------------------------------------------------- |
| `RuntimeNotInstalled` | `load_runtime()` cannot import the selected runtime. |

## Environment

| Variable        | Default     | Effect                                                   |
| --------------- | ----------- | -------------------------------------------------------- |
| `TELYS_RUNTIME` | `""` (auto) | Force `"native"` or `"local"` runtime selection.         |
| `TELYS_KERNEL`  | —           | Force the native kernel library path (highest priority). |
| `AME_KERNEL`    | —           | Legacy kernel path override.                             |

A verified install lives under `$TELYS_HOME/runtime/<platform>/` (default `~/.telys`), containing `libty_runtime`, `libame_kernel`, `telys_manifest.json`, `telys_manifest.sig`, `license.jwt`, `installed.json`, and `pysite/`. Importing `telys` prepends that `pysite/` to `sys.path` when the install is verified.

## Installing & verifying the runtime

Install and verify through the CLI, not this API:

```bash
telys runtime status    # 0 ready / 1 not installed
telys runtime install   # download + install the signed runtime
telys runtime verify    # verify the signature + license offline
```

{% hint style="warning" %}
`telys runtime update` is a stub in this release: it prints "not implemented yet" and exits `2`. To move to a new runtime, re-run `telys runtime install --version …`.
{% endhint %}

## See also

<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>The signed runtime &#x26; trust model</strong></td><td>Why the runtime is separate and signed.</td><td><a href="/pages/VmHkD0an28Ww8yTFnwpS">/pages/VmHkD0an28Ww8yTFnwpS</a></td></tr><tr><td><strong>telys runtime</strong></td><td>CLI for install, status, and verify.</td><td><a href="/pages/5Vd47RwOO39CSEHoL96V">/pages/5Vd47RwOO39CSEHoL96V</a></td></tr><tr><td><strong>Install &#x26; runtime issues</strong></td><td>Fix a runtime that will not load.</td><td><a href="/pages/sTZH257W259P14bHy2EA">/pages/sTZH257W259P14bHy2EA</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Where the runtime and collections live.</td><td><a href="/pages/2zslEGbkkXRBUP6ppFSD">/pages/2zslEGbkkXRBUP6ppFSD</a></td></tr></tbody></table>


---

# 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/reference/runtime-api.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.