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

# telys runtime

Reference for telys runtime — check status, install (offline or hosted), and verify the signed native runtime. telys runtime update is a stub.

Manage the signed native runtime — the signed engine Telys loads to run any collection operation. Check whether it is installed, install it (from a local file or a hosted download), and verify its signature offline.

## Synopsis

```
telys runtime status
telys runtime install [--file FILE] [--license LICENSE] [--version VERSION]
telys runtime verify
telys runtime update                   # stub — not implemented, exits 2
```

Installed runtimes live under `$TELYS_HOME/runtime/<platform>/` (default `~/.telys/runtime/...`) alongside the signed manifest, its signature, the license, and an activated `pysite/`.

## `telys runtime status`

Report whether a verified runtime is installed and activated for this platform.

```bash
telys runtime status
```

| Code | Meaning                                        |
| ---- | ---------------------------------------------- |
| `0`  | A runtime is installed and ready.              |
| `1`  | No runtime is installed (or it is not usable). |

The exit code composes cleanly in scripts:

```bash
telys runtime status || telys runtime install
```

## `telys runtime install`

Install the signed runtime for your platform.

| Flag        | Value   | Default  | Meaning                                                                                                                                                                                                                                                                                         |
| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file`    | path    | (none)   | Install from a local signed runtime archive — a fully supported, network-free path.                                                                                                                                                                                                             |
| `--license` | path    | (none)   | Path to the signed offline license file (`license.jwt`). Required with `--file`. For hosted installs, without it the CLI uses the license cached by `telys login` (`$TELYS_HOME/login_license.jwt`), and otherwise fetches it from the host's license endpoint (OEM download-token hosts only). |
| `--version` | version | `latest` | Which runtime version to fetch when downloading.                                                                                                                                                                                                                                                |

Two ways to install:

{% tabs %}
{% tab title="Offline (--file)" icon="box" %}
No network required. Point `install` at a signed archive you already have, together with its signed offline license — for example on an air-gapped host:

```bash
telys runtime install --file ./telys-runtime-macos-arm64.tar --license ./license.jwt
```

`--license` is required for `--file` installs — the install fails without it. The archive's signed manifest and the license are both verified before anything is activated.
{% endtab %}

{% tab title="Hosted download" icon="cloud-arrow-down" %}
Without `--file`, `install` downloads the signed runtime from the packages host (`$TELYS_PACKAGES_URL`, default `https://packages.telys.ai`):

```bash
telys runtime install                 # latest for this platform
telys runtime install --version 1.4.0 # a specific version
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`telys login` installs the runtime by default, so a fresh sign-in usually means you never run `install` by hand. Use it for air-gapped installs (`--file`), to re-install, or to pin a specific `--version`.
{% endhint %}

Verified installs are native-only and fail closed: if the signature or license does not check out, the runtime is not activated.

## `telys runtime verify`

Re-verify the installed runtime's signature and manifest, entirely offline. Verification uses the release public key embedded in the wheel (override with `$TELYS_RELEASE_PUBKEY` / `_FILE`).

```bash
telys runtime verify
```

| Code | Meaning                                         |
| ---- | ----------------------------------------------- |
| `0`  | Signature and manifest verified.                |
| `1`  | Verification failed or no runtime is installed. |

These are the same checks exposed programmatically in the [Runtime API](https://docs.telys.ai/reference/runtime-api.md). There is no standalone `telys verify` command — signature verification is `telys runtime verify`.

## `telys runtime update`

{% hint style="warning" %}
`telys runtime update` is a stub: it prints a "not implemented yet" message and exits `2`. To move to a newer runtime, run `telys runtime install` (with `--version` to pin, or `--file` for an offline archive).
{% endhint %}

```bash
telys runtime update
# not implemented yet
# (exit code 2)
```

## See also

* [Verify your install](https://docs.telys.ai/start-here/verify-install.md) — the guided post-install check.
* [Verify the runtime signature](https://docs.telys.ai/security/runtime-signature-verification.md) — the trust model behind `verify`.
* [The signed runtime & trust model](https://docs.telys.ai/understand-telys/signed-runtime-trust.md) — why the engine is signed.
* [Runtime API](https://docs.telys.ai/reference/runtime-api.md) — `load_runtime` and `runtime_available` in the SDK.
