> 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

Why every Telys collection, embedding, and search runs on your machine, the short list of things that ever use the network, and how it works fully offline after first login.

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="/security/what-leaves-the-machine.md">What leaves the machine</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="/licensing/offline-licenses.md">Offline licenses</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="/security/data-residency-privacy.md">Data residency</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="/understand-telys/local-vs-remote.md">Local vs remote</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.telys.ai/understand-telys/on-device-offline.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.