Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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.

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.

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:

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.

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>.

Next steps

Last updated

Was this helpful?