> 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/security/overview.md).

# Overview

Telys keeps the sensitive parts of a vector-memory system — your documents, their embeddings, and your queries — on the machine that runs the SDK, and proves the code that runs there is the code Telys published. Two ideas define the posture: **on-device, offline-first execution** (your data never needs the network) and **three cryptographic trust anchors** (the runtime is signed, hash-verified, and licensed before it activates). This page maps the posture; each section links to the detail.

## The posture in one paragraph

The `telys` package is thin, open Python. It defines the API, verifies signatures and licenses, and lazily loads a signed native runtime through `ctypes`. Before the runtime activates, the SDK verifies a signed release manifest, hashes every artifact against it, and validates an offline license — all against public keys embedded in the wheel, with no network call. After provisioning, every collection operation (create, add, embed, search, compact, save, serve) runs in-process on your hardware. The network handles only a small, enumerable set of account-and-delivery tasks — never storing or querying your data.

## The three trust anchors

Three independent checks gate every native call. All must pass, or the runtime does not load.

| Anchor                       | What it proves                                                                          | Primitive                                                                                            |
| ---------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Signed release manifest**  | The manifest of versions and hashes was published by Telys and is byte-for-byte intact. | RS256 / PKCS#1 v1.5 + SHA-256 over the exact manifest bytes, against the embedded release key.       |
| **Verified artifact hashes** | Each native library on disk is exactly the file the manifest promises.                  | Per-artifact SHA-256, compared in constant time to the signed manifest.                              |
| **Offline license**          | This machine is entitled to run Telys, and the token has not expired.                   | Strict offline RS256 check of `license.jwt` — `iss` / `aud` / `ver == 2` / `exp` + `products.telys`. |

See [**Three trust anchors**](/security/trust-anchors.md) for the exact algorithms, the fail-closed behavior, and the constants each check pins.

## What leaves the machine

The data path is entirely local. Your vectors, document text, and metadata never cross the network to make search work. The only outbound traffic is three account-and-delivery tasks:

| The network is used only for…                  | Host (env var)                             | When                                            |
| ---------------------------------------------- | ------------------------------------------ | ----------------------------------------------- |
| Device-code sign-in                            | `accounts.thyn.ai` (`TELYS_ACCOUNTS_URL`)  | `telys login`                                   |
| Control plane (keys, device, license issuance) | `api.telys.ai` (`TELYS_API_URL`)           | login / install                                 |
| Signed-runtime download                        | `packages.telys.ai` (`TELYS_PACKAGES_URL`) | `telys runtime install` (skipped with `--file`) |

`telys serve` makes **no outbound network calls**, and the MCP server runs over local stdio. For the byte-level accounting, see [**What leaves the machine**](/security/what-leaves-the-machine.md).

{% hint style="warning" %}
One exception is yours to control: if you wire a `CallableEmbedder` to a remote embedding API (for example OpenAI or a hosted BGE endpoint), your code sends that text to the service. The on-device guarantee covers Telys and its local `telys.embedding` kernels; a remote embedder is a network call you own.
{% endhint %}

## Threat model at a glance

Telys's design addresses a specific set of threats. It does not replace host and OS security.

**In scope — what Telys defends against:**

| Threat                                          | How Telys addresses it                                                                                                     |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| A tampered or forged release manifest           | RS256 signature over the exact manifest bytes; a modified manifest fails verification.                                     |
| A swapped or corrupted native library           | SHA-256 of every artifact is compared, in constant time, to the signed manifest.                                           |
| A forged, wrong-product, or expired license     | Strict offline RS256 check pinning algorithm, `iss`, `aud`, `ver == 2`, `exp` + grace, and `products.telys`.               |
| Silent downgrade to unsigned code               | A verified install is native-only and fail-closed — it refuses to run rather than load something unverified.               |
| Data exfiltration by the engine                 | `serve()` makes no outbound calls; no vector, text, or query is ever sent off the machine.                                 |
| Anonymous network access to a served collection | TCP `serve` requires an `access_token` (constant-time compare); the Unix socket is created `0o600` and treated as trusted. |

**Out of scope — what you still own:**

* **Encryption at rest.** Collection files under `$TELYS_HOME` are stored as the runtime writes them; use full-disk or filesystem encryption for at-rest protection.
* **Host and OS compromise.** Anyone with read access to `$TELYS_HOME`, or root on the machine, can read your data. File-permission hardening (for example the `0600` device key) reduces but does not eliminate this.
* **Your own outbound calls.** A remote `CallableEmbedder`, or your application code, may send data over the network independently of Telys.
* **Transport encryption for `serve` over TCP.** The access-token gate authenticates the caller; put TCP deployments behind a trusted network or a TLS-terminating proxy (see [**Auth & network model**](/self-hosting/auth-and-network.md)).

## Fail-closed and native-only

The trust model has no soft failure. `load_runtime()` never downgrades a verified install to unverified code; if the runtime cannot import, it raises `RuntimeNotInstalled` rather than degrading. Importing the package (`import telys`) activates only a verified install's `pysite/` — otherwise it is a silent no-op. An install that does not verify does not run.

{% hint style="info" %}
`telys runtime verify` is the one command that exercises all three anchors. It runs entirely offline and exits `0` only when the signature, hashes, and license all pass. There is no standalone `telys verify` command.
{% 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>Three trust anchors</strong></td><td>The signature, hashes, and license in depth.</td><td><a href="/pages/IfZ7h0ml3OjlVuNi4tGX">/pages/IfZ7h0ml3OjlVuNi4tGX</a></td></tr><tr><td><strong>What leaves the machine</strong></td><td>The exact bytes that cross the network, and when.</td><td><a href="/pages/0hje8J5hOfSb7uBhwgsG">/pages/0hje8J5hOfSb7uBhwgsG</a></td></tr><tr><td><strong>Verify the runtime signature</strong></td><td>Run the full verification chain yourself.</td><td><a href="/pages/as3JvHboA5RxokqNHpAw">/pages/as3JvHboA5RxokqNHpAw</a></td></tr><tr><td><strong>Data residency &#x26; privacy</strong></td><td>Where your data lives and who can see it.</td><td><a href="/pages/czd8vgdLG6PP6tkAwVVq">/pages/czd8vgdLG6PP6tkAwVVq</a></td></tr></tbody></table>

Next: understand the cryptography in [**Three trust anchors**](/security/trust-anchors.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/security/overview.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.