> 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 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`. | | `//collection.json` | The per-collection commit point (name, dim, dtype, key, profile, tuning). | | `//id_map.npy` | The external-id sidecar. | | `//` (slab files) | The runtime's vector data. | | `runtime//` | 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**](/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**](/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
What leaves the machineThe exact outbound traffic, and what never leaves./pages/0hje8J5hOfSb7uBhwgsG
On-device & offline-firstWhy the data path needs no network./pages/8qFzJkRN9mhP0vZqJwZv
On-disk layoutEvery file Telys writes under $TELYS_HOME./pages/2zslEGbkkXRBUP6ppFSD
Security overviewThe full posture and threat model./pages/jLlQKGv5GwnJU5gn4Frl
Next: audit the outbound traffic in [**What leaves the machine**](/security/what-leaves-the-machine.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/data-residency-privacy.md?ask=&goal= ``` `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.