Install

Install the Telys SDK with pipx or pip on Python 3.10+, then provision the signed native runtime for your platform with a single telys login.

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.

• 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.

pipx

pipx install telys

Preferred for the CLI. pipx isolates Telys in its own virtual environment and exposes the telys entry point globally.

pip

pip install telys

Use this to import telys from your own project's environment. Use a virtual environment to avoid dependency conflicts.

Steps

1

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.

2

Provision the signed runtime

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>/.

3

Confirm the version

telys version

Prints the SDK version and on-disk format version. Works before login — it does not need the runtime.

Expected result

telys version prints the version and format contract:

telys 0.1.15 (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:

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

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.

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.

Next steps

Sign in & activate a license

Details of the device-code flow, tokens, and plans.

Verify your install

Check runtime readiness and the signature offline.

Quickstart: your first collection

Create, add, and search on-device in minutes.

Next: Sign in & activate a license, then run the Quickstart.