> 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/data-residency-privacy.md).

# Data residency

Where Telys keeps your data — on your own disk under $TELYS\_HOME, with no content telemetry — and why that makes it suitable for regulated and air-gapped deployments.

Data residency with Telys is easy to reason about: your collections live on the disk of the machine that runs the SDK, under a directory you control, and Telys never sends the contents anywhere. This page covers where data rests, what is and is not collected, and how that maps to regulated and air-gapped use.

## Your data stays on your disk

Every collection Telys writes lives under `$TELYS_HOME` (default `~/.telys`), on the local filesystem. There is no hosted store and no sync — your data's residency is that directory's residency.

The on-disk state:

| Path (under `$TELYS_HOME`)                                                      | Contents                                                                  |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `memory/`                                                                       | The default engine directory used by MCP and `telys mem`.                 |
| `<engine>/<collection>/collection.json`                                         | The per-collection commit point (name, dim, dtype, key, profile, tuning). |
| `<engine>/<collection>/id_map.npy`                                              | The external-id sidecar.                                                  |
| `<engine>/<collection>/` (slab files)                                           | The runtime's vector data.                                                |
| `runtime/<platform>/`                                                           | The verified runtime, kernel, signed manifest, and cached `license.jwt`.  |
| `token`, `api_key`, `device_key.pem` (`0600`), `device_id`, `login_license.jwt` | Cached credentials and the Ed25519 device identity.                       |

Pass an explicit path to `Telys("./data")` or `telys serve --path ./data` and your collections live there instead. Either way the data never leaves the host — move `$TELYS_HOME` to an encrypted volume or a specific mount to control residency. See [**On-disk layout**](https://docs.telys.ai/operations/on-disk-layout.md).

```python
from telys import Telys
from telys.embedding import AlgentaBigramEmbedder

# Data is written under ./data on THIS machine — nowhere else.
db = Telys("./data")
emb = AlgentaBigramEmbedder()
col = db.create_collection("notes", dim=emb.profile.dimension, partition_by="scope",
                           embedder=emb)
col.add_texts(["a private note"], ids=["n1"], metadata=[{"scope": "me"}])
col.save()   # persists to ./data/notes/ — no upload
```

## No telemetry of your content

Telys does not collect, transmit, or phone home your documents, embeddings, queries, or metadata. Data-path operations make no outbound calls, `telys serve` makes no outbound calls, and license **verification** is offline against a key embedded in the wheel. The only network traffic Telys produces is account sign-in, the control-plane calls that register your device and issue a license, and the one-time signed-runtime download — enumerated on [**What leaves the machine**](https://docs.telys.ai/security/what-leaves-the-machine.md).

{% hint style="success" %}
Nothing about a search — not the query text, the query vector, or the results — is sent anywhere. Embedding runs on your CPU through the local `telys.embedding` kernels; matching runs in the runtime.
{% endhint %}

{% hint style="warning" %}
The content guarantee covers Telys and its local embedders. A `CallableEmbedder` backed by a hosted embedding API sends that text off the machine by your code, not by Telys. Choose a local embedder to keep the full path on-device.
{% endhint %}

## Suitable for regulated and air-gapped use

The data path is fully local and license verification is offline, so Telys runs where outbound connectivity is restricted or forbidden — **after** the one-time provisioning step.

* **Regulated data.** Collections with sensitive or regulated content never traverse a network to be embedded, indexed, or searched, so the data-processing boundary is the host. Add full-disk or filesystem encryption for at-rest requirements (Telys adds no at-rest encryption of its own).
* **Air-gapped installs.** The target machine never needs to go online. `telys runtime install --file telys-runtime-linux-x86_64.tar --license license.jwt` installs from local files with zero network, and `telys runtime verify` then re-checks the signature, hashes, and license offline. After that, no further outbound access is needed.

```bash
# On an air-gapped host — install from files, verify offline, then run.
telys runtime install --file telys-runtime-linux-x86_64.tar --license license.jwt
telys runtime verify        # exit 0 = signature + hashes + license valid, offline
```

{% hint style="info" %}
Provisioning — `telys login` on a connected machine, or copying a runtime bundle plus `license.jwt` across an air gap — is the one step that needs the network or a file transfer. Everything after, including license verification, is offline. Supported runtime platforms are `macos-arm64`, `linux-x86_64`, and `linux-arm64` (experimental); on Windows, use WSL2.
{% endhint %}

## What you still own

Telys secures the runtime and keeps your data local; the host is yours to protect:

* **Encryption at rest** comes from your OS or volume, not Telys.
* **Filesystem access** to `$TELYS_HOME` grants read access to your collections — restrict it with OS permissions.
* **Backups and retention** of `$TELYS_HOME` (or your engine path) are yours; the on-disk format is stable at `FORMAT_VERSION = 1`.

## 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>What leaves the machine</strong></td><td>The exact outbound traffic, and what never leaves.</td><td><a href="https://docs.telys.ai/security/what-leaves-the-machine.md">What leaves the machine</a></td></tr><tr><td><strong>On-device &#x26; offline-first</strong></td><td>Why the data path needs no network.</td><td><a href="https://docs.telys.ai/understand-telys/on-device-offline.md">On-device &amp; offline</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Every file Telys writes under <code>$TELYS_HOME</code>.</td><td><a href="https://docs.telys.ai/operations/on-disk-layout.md">On-disk layout</a></td></tr><tr><td><strong>Security overview</strong></td><td>The full posture and threat model.</td><td><a href="https://docs.telys.ai/security/overview.md">Overview</a></td></tr></tbody></table>

Next: audit the outbound traffic in [**What leaves the machine**](https://docs.telys.ai/security/what-leaves-the-machine.md).
