> 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/understand-telys/signed-runtime-trust.md).

# Signed runtime & trust

How Telys verifies a signed release manifest, hashes every runtime artifact, and checks an offline license before activating the native engine — fail-closed, native-only.

The `telys` SDK is pure Python, but the engine it drives — the native runtime and the embedding kernel — ships as a **signed bundle**. Before that bundle is activated, the SDK verifies three things: a release manifest signed by Telys's release key, every on-disk artifact matching the hash the manifest promises, and a valid offline license for this machine. Any check fails and the runtime does not load. This page describes that chain and the API you run yourself.

## What ships signed

A verified install lands under `$TELYS_HOME/runtime/<platform>/` (for example `runtime/macos-arm64/`) and contains the runtime, the kernel, the signed manifest, and the license:

| File                        | Role                                                       |
| --------------------------- | ---------------------------------------------------------- |
| `libty_runtime.<ext>`       | the native runtime (`.dylib` / `.so` / `.dll`)             |
| `libame_kernel.<ext>`       | the embedding kernel                                       |
| `telys_manifest.json`       | the release manifest (versions + expected artifact hashes) |
| `telys_manifest.sig`        | RS256 / PKCS#1 v1.5 signature over the manifest            |
| `license.jwt`               | the offline license token                                  |
| `installed.json`, `pysite/` | install metadata and the runtime's Python site directory   |

## The verification chain

The SDK walks three anchors in order, and every one must pass.

{% stepper %}
{% step %}

#### Verify the release manifest signature

`verify_manifest(manifest_bytes, signature, pubkey=None)` checks `telys_manifest.sig` against `telys_manifest.json` with RS256 / PKCS#1 v1.5 and SHA-256, defaulting to the embedded release public key, and returns the trusted manifest as a dict. A tampered or unsigned manifest fails here, so nothing downstream is believed.
{% endstep %}

{% step %}

#### Verify every artifact hash

For each artifact the manifest describes, `verify_artifact(path, expected_sha256)` recomputes the file's SHA-256 (via `sha256_file`) and compares it in **constant time** to the value the signed manifest promised. A swapped or corrupted `libty_runtime` / `libame_kernel` is rejected here.
{% endstep %}

{% step %}

#### Verify the offline license

`verify_license(token, pubkey=None, *, now, issuer=None, audience=None, product="telys")` validates `license.jwt` strictly and entirely offline against the embedded license public key: it pins the algorithm to RS256, rejects any `crit` header, checks `iss` / `aud` / `ver == 2` and `exp` plus a grace window, and reads the `products.telys` tier and features. Only then is the runtime activated.
{% endstep %}
{% endstepper %}

## Fail-closed and native-only

A verified install is **native-only**. `load_runtime()` loads the signed native runtime for a native or verified install and never silently downgrades a verified install to the local runtime. If the runtime cannot be imported it raises `RuntimeNotInstalled` rather than degrading — the trust model is fail-closed, so an install that does not verify simply does not run.

Importing the package wires it in: `import telys` prepends the verified install's `pysite/` to `sys.path` (a silent no-op when there is none). `TELYS_RUNTIME` can force `"native"` or `"local"` to override auto-detection.

## The embedded trust anchors

The public keys the SDK trusts are shipped **inside the wheel**, so verification needs no network and no external key server:

* `release_public_key()` → `telys/_keys/telys_release_pub.pem` (verifies the manifest)
* `license_public_key()` → `telys/_keys/telys_license_pub.pem` (verifies the license)

Both require the `cryptography` package (a hard SDK dependency). You can override the keys and license expectations via environment — `TELYS_RELEASE_PUBKEY` / `TELYS_RELEASE_PUBKEY_FILE`, `TELYS_LICENSE_PUBKEY` / `TELYS_LICENSE_PUBKEY_FILE`, `TELYS_LICENSE_ISSUER`, and `TELYS_LICENSE_AUDIENCE` — but the defaults are the production trust anchors.

| Constant                    | Default                            |
| --------------------------- | ---------------------------------- |
| `DEFAULT_LICENSE_ISSUER`    | `https://license.algenta.ai`       |
| `DEFAULT_LICENSE_AUDIENCES` | `telys-runtime`, `algenta-runtime` |
| `SUPPORTED_LICENSE_VER`     | `2`                                |
| `PRODUCT`                   | `telys`                            |

## Verify it yourself

The one-command path runs the whole chain and is the recommended check after any install or upgrade:

```bash
telys runtime verify        # exit 0 when signature + hashes + license all pass
```

{% hint style="warning" %}
There is no standalone `telys verify` command — signature verification is `telys runtime verify` plus the `telys.verify` API below.
{% endhint %}

For scripting or auditing, the same primitives are importable. The manifest bytes, signature, expected hashes, and license token all come from the signed bundle in `$TELYS_HOME/runtime/<platform>/`:

```python
import datetime
from telys.verify import (
    release_public_key,
    license_public_key,
    verify_manifest,
    verify_artifact,
    verify_license,
    sha256_file,
)

# The public keys the SDK trusts (from the embedded PEMs).
release_pub = release_public_key()
license_pub = license_public_key()

# 1. Manifest signature -> trusted manifest dict (RS256 / PKCS1v15 / SHA-256).
manifest = verify_manifest(manifest_bytes, signature)

# 2. Artifact integrity -> raises if a file's SHA-256 does not match.
verify_artifact("libty_runtime.dylib", expected_sha256)   # expected value from the manifest

# 3. Offline license -> claims dict; strict, no network, pins RS256, ver == 2.
now = int(datetime.datetime.now(datetime.timezone.utc).timestamp())  # verify_license wants a Unix int
claims = verify_license(license_jwt, now=now)
print(claims["products"]["telys"])   # tier + features
```

## Next steps

<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>Security overview</strong></td><td>The whole trust posture, end to end.</td><td><a href="/security/overview.md">Overview</a></td></tr><tr><td><strong>Three trust anchors</strong></td><td>Release key, license key, and artifact hashes in depth.</td><td><a href="/security/trust-anchors.md">Trust anchors</a></td></tr><tr><td><strong>Verify the runtime signature</strong></td><td>Run the verification chain step by step.</td><td><a href="/security/runtime-signature-verification.md">Verify the runtime</a></td></tr><tr><td><strong>Verify your install</strong></td><td>Confirm the runtime is installed and trusted.</td><td><a href="/start-here/verify-install.md">Verify install</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.telys.ai/understand-telys/signed-runtime-trust.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.