> 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/start-here/install.md).

# Install

Installing Telys takes two steps: install the `telys` SDK from PyPI, then run `telys login` once to download and verify the signed native runtime for your platform. The SDK is pure Python; the runtime is the engine it loads through `ctypes`.

## Prerequisites

* **Python 3.10 or newer.** Wheels are pure-Python (`py3-none-any`) and classifiers list 3.10 through 3.13; 3.14 works too since the runtime loads via `ctypes`.
* **A supported platform for the runtime:** `macos-arm64`, `linux-x86_64`, or `linux-arm64` (experimental). Windows runs under WSL2. Intel Macs are not yet supported — see [**Supported platforms**](/operations/supported-platforms.md).
* **Network access for the first login only.** The runtime is downloaded and verified once, then runs fully offline.

## Install the SDK

`numpy` and `cryptography` install automatically. Use `pipx` for an isolated environment with the `telys` command on your PATH; use `pip` to install into the current environment.

{% tabs %}
{% tab title="pipx" icon="terminal" %}

```bash
pipx install telys
```

Preferred for the CLI. `pipx` isolates Telys in its own virtual environment and exposes the `telys` entry point globally.
{% endtab %}

{% tab title="pip" icon="python" %}

```bash
pip install telys
```

Use this to `import telys` from your own project's environment. Use a virtual environment to avoid dependency conflicts.
{% endtab %}
{% endtabs %}

## Steps

{% stepper %}
{% step %}

#### Install the package

Run one of the commands above. It installs the SDK, `numpy>=1.24`, and `cryptography>=42`, and registers the `telys` console command.
{% endstep %}

{% step %}

#### Provision the signed runtime

```bash
telys login
```

`telys login` completes a device-code sign-in in your browser, activates a license, then downloads and verifies the signed runtime offline against the public keys embedded in the wheel. On success, it is stored under `~/.telys/runtime/<platform>/`.
{% endstep %}

{% step %}

#### Confirm the version

```bash
telys version
```

Prints the SDK version and on-disk format version. Works before login — it does not need the runtime.
{% endstep %}
{% endstepper %}

## Expected result

`telys version` prints the version and format contract:

```
telys 0.1.0b2 (format v1)
```

After `telys login`, the runtime is installed and verified, and `import telys` activates it automatically. Confirm end to end with [**Verify your install**](/start-here/verify-install.md):

```bash
telys runtime status
echo $?          # 0 = runtime ready, 1 = not installed
```

{% hint style="info" %}
The runtime is fetched and signature-checked only on that first login. After that, Telys makes no outbound network calls — collections, embeddings, and search run locally, offline.
{% endhint %}

{% hint style="warning" %}
Installing the SDK alone cannot create collections: every collection operation runs in the runtime, and the lexical embedders need the native kernel. Skip `telys login` and constructing an embedder or opening a collection raises an error until the runtime is installed. Importing an embedder still succeeds — the error surfaces when you construct or use it.
{% endhint %}

## 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>Sign in &#x26; activate a license</strong></td><td>Details of the device-code flow, tokens, and plans.</td><td><a href="/pages/jbtYRrlfm2suAHJekJo2">/pages/jbtYRrlfm2suAHJekJo2</a></td></tr><tr><td><strong>Verify your install</strong></td><td>Check runtime readiness and the signature offline.</td><td><a href="/pages/h4z9ZPSmvEnW3qsGotXt">/pages/h4z9ZPSmvEnW3qsGotXt</a></td></tr><tr><td><strong>Quickstart: your first collection</strong></td><td>Create, add, and search on-device in minutes.</td><td><a href="/pages/3P7KO0CUnD1NfTy6KAyk">/pages/3P7KO0CUnD1NfTy6KAyk</a></td></tr></tbody></table>

Next: [**Sign in & activate a license**](/start-here/sign-in.md), then run the [**Quickstart**](/quickstarts/quickstart-first-collection.md).


---

# 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/start-here/install.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.