> 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/understand-telys/on-device-offline.md).

# On-device & offline

Your data never has to leave the machine it lives on. Collections, embeddings, indexes, and every query run in-process against the local native runtime; no vector, document text, or metadata is sent anywhere to make search work. The network serves only a small set of account and delivery tasks — and once those are done, Telys works fully offline, including air-gapped.

## What runs on your machine

The entire data path is local. Creating a collection, ingesting text, embedding, indexing, and searching all happen in your process via the runtime and the embedding kernel:

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

# In-process, on this machine. No network. Nothing leaves.
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.search_text("private", top_k=5)
col.save()
```

The `telys.embedding` embedders compute vectors locally through the native kernel — text becomes vectors on your CPU, not shipped to an embedding service. Serving is local too: `telys serve` makes **no outbound network** calls, and the MCP server runs over local stdio.

## What uses the network

Network access is limited to three account-and-delivery tasks, and nothing else:

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

Creating collections, adding and upserting records, embedding, searching, compacting, saving, serving, and answering MCP tool calls make none of these calls. License **verification** is offline — the SDK checks the cached license against an embedded public key locally, so an install you have already set up never requires being online.

{% hint style="success" %}
The guarantee: your vectors, document text, and metadata never cross the network. The only bytes that do are the auth tokens exchanged during `telys login` and the signed runtime you download once.
{% endhint %}

## After first login, you're offline

The first `telys login` and `telys runtime install` are the only steps that need connectivity. They cache everything required to run under `$TELYS_HOME` (default `~/.telys`):

* Credentials and identity: `token`, `api_key`, `device_key.pem` (an Ed25519 device key, mode `0600`), `device_id`, and `login_license.jwt`.
* The verified runtime: `runtime/<platform>/` holding `libty_runtime`, `libame_kernel`, the signed `telys_manifest.json` + `telys_manifest.sig`, and the offline `license.jwt`.

From then on everything works with the network off. The cached license is verified locally on each activation — strictly, with an `exp` plus grace window — so short outages and travel do not lock you out.

```bash
# One-time, online: sign in and fetch the signed runtime + license.
telys login
telys runtime install          # downloads from packages.telys.ai, then verifies

# Everything after this works with the network off:
telys runtime status           # exit 0 = installed, verified, offline-capable
telys runtime verify           # re-checks signature + hashes + license, offline
```

## Fully offline and air-gapped installs

The target machine never needs to go online. `telys runtime install` accepts a local bundle and a license file, so you can move both across an air gap and install with zero network:

```bash
# On the air-gapped machine — install straight from files, no network.
telys runtime install --file telys-runtime-macos-arm64.tar --license license.jwt
telys runtime verify
```

The `--file` path is fully supported; only the hosted download it replaces would have touched `packages.telys.ai`. After this, the machine has a verified, offline runtime and never needs to reach out again.

{% hint style="info" %}
Supported runtime platforms are `macos-arm64`, `linux-x86_64`, and `linux-arm64` (the last is experimental); on Windows, run under WSL2. The bundle you copy must match the target's `<os>-<arch>`.
{% 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>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>Offline licenses &#x26; verification</strong></td><td>How the cached license is checked without a network.</td><td><a href="/pages/uRMcsbR2tREfJPlvdVTx">/pages/uRMcsbR2tREfJPlvdVTx</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><tr><td><strong>Local vs remote execution</strong></td><td>When to serve a collection instead of running in-process.</td><td><a href="/pages/pDAqCOdYa0pJZlwE3c5A">/pages/pDAqCOdYa0pJZlwE3c5A</a></td></tr></tbody></table>


---

# 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/understand-telys/on-device-offline.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.