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:
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, mode0600),device_id, andlogin_license.jwt.The verified runtime:
runtime/<platform>/holdinglibty_runtime,libame_kernel, the signedtelys_manifest.json+telys_manifest.sig, and the offlinelicense.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.
Next steps
Last updated
Was this helpful?