> 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

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` | token   | (none)   | License token to bind the install to; otherwise the license cached by `telys login` is used. |
| `--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 — for example on an air-gapped host:

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

The archive's signed manifest is 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 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/cli/runtime.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.