> 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

Reference for telys.runtime — load\_runtime, runtime\_available, the RuntimeHandle interface, FORMAT\_VERSION, RuntimeNotInstalled, and the TELYS\_RUNTIME switch.

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="https://docs.telys.ai/understand-telys/signed-runtime-trust.md">Signed runtime &amp; trust</a></td></tr><tr><td><strong>telys runtime</strong></td><td>CLI for install, status, and verify.</td><td><a href="https://docs.telys.ai/cli/runtime.md">telys runtime</a></td></tr><tr><td><strong>Install &#x26; runtime issues</strong></td><td>Fix a runtime that will not load.</td><td><a href="https://docs.telys.ai/troubleshooting/install-and-runtime.md">Install &amp; runtime</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Where the runtime and collections live.</td><td><a href="https://docs.telys.ai/operations/on-disk-layout.md">On-disk layout</a></td></tr></tbody></table>
