> 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](/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](/start-here/verify-install.md) — the guided post-install check.
* [Verify the runtime signature](/security/runtime-signature-verification.md) — the trust model behind `verify`.
* [The signed runtime & trust model](/understand-telys/signed-runtime-trust.md) — why the engine is signed.
* [Runtime API](/reference/runtime-api.md) — `load_runtime` and `runtime_available` in the SDK.


---

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