> 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/operations/on-disk-layout.md).

# On-disk layout

Telys persists everything under one root, `$TELYS_HOME` (default `~/.telys`): cached credentials from `telys login`, the verified native runtime, and the default memory directory for the MCP server and `telys mem`. Collections you create in Python live wherever you point `Telys(path)`, with the same directory structure everywhere.

These are plain files — inspect, back up, and delete them directly.

## The `$TELYS_HOME` tree

```
~/.telys/                       # $TELYS_HOME — root of all state
├── token                       # cached control-plane token
├── api_key                     # cached Telys API key
├── device_key.pem              # Ed25519 device key (mode 0600)
├── device_id                   # this device's id (uuid4 hex)
├── login_license.jwt           # license issued by `telys login`
├── memory/                     # default MCP / `telys mem` engine dir
│   └── <collection>/           # one directory per saved collection
│       ├── collection.json     # manifest + commit point
│       ├── id_map.npy          # external-id ↔ internal-row map
│       └── <slab files>        # runtime vector slabs
└── runtime/
    └── macos-arm64/            # platform_tag(): <os>-<arch>
        ├── libty_runtime.dylib # closed engine runtime
        ├── libame_kernel.dylib # native embedding kernel
        ├── telys_manifest.json # signed manifest of this install
        ├── telys_manifest.sig  # RS256 signature over the manifest
        ├── license.jwt         # runtime license
        ├── installed.json      # install metadata / provenance
        └── pysite/             # prepended to sys.path on `import telys`
```

## Root-level files

Written by `telys login` and the control-plane client:

| File                | Contents                                                   |
| ------------------- | ---------------------------------------------------------- |
| `token`             | Cached control-plane auth token.                           |
| `api_key`           | Cached Telys API key.                                      |
| `device_key.pem`    | Ed25519 private key identifying this device (mode `0600`). |
| `device_id`         | The device id, a uuid4 in hex.                             |
| `login_license.jwt` | The license token returned by device-code sign-in.         |

{% hint style="warning" %}
`device_key.pem`, `token`, and `api_key` are secrets, created with restrictive permissions. Keep them that way and never commit them to version control.
{% endhint %}

## The runtime directory

`telys runtime install` writes a verified install under `runtime/<platform>/`, where `<platform>` is `platform_tag()` — `<os>-<arch>`, for example `macos-arm64` or `linux-x86_64`. The library extension follows the OS: `.dylib` (macOS), `.so` (Linux), `.dll` (Windows).

| File                  | Role                                                                             |
| --------------------- | -------------------------------------------------------------------------------- |
| `libty_runtime.<ext>` | The closed engine runtime loaded via ctypes.                                     |
| `libame_kernel.<ext>` | Native kernel that backs the `Algenta*` embedders.                               |
| `telys_manifest.json` | Signed manifest listing artifacts and their SHA-256 hashes.                      |
| `telys_manifest.sig`  | RS256 signature over the manifest, checked against the release key.              |
| `license.jwt`         | Runtime license verified offline at load time.                                   |
| `installed.json`      | Install metadata (version, provenance).                                          |
| `pysite/`             | Python site directory prepended to `sys.path` when a verified install is active. |

On `import telys`, a present verified install has its `pysite/` prepended to `sys.path`, making the runtime importable; without one, this is a silent no-op. `telys runtime verify` re-checks the manifest signature and every artifact hash.

## Per-collection files

Each collection is a directory. Under the default MCP store it lives at `memory/<name>/`; the same shape appears under any path you pass to `Telys(path)`.

| File              | Role                                                              |
| ----------------- | ----------------------------------------------------------------- |
| `collection.json` | The manifest and the **commit point** — written last on `save()`. |
| `id_map.npy`      | Sidecar mapping external ids to internal rows.                    |
| slab files        | Runtime-managed vector slabs holding the actual vectors.          |

`Collection.save()` writes the `id_map.npy` sidecar first, then `collection.json` last. Because the manifest is the final write, a collection counts as saved only once it exists: a half-written save leaves no valid `collection.json`, and `collections()` lists only directories that contain one.

`collection.json` records `name`, `dim`, `dtype`, `key_name`, `filter_columns`, the id-map sidecar reference, `telys_version`, `default_target_recall`, the applied tuner, and the embedder profile. The profile lets `open_collection()` re-attach the right embedder from your provider registry by its space id.

{% hint style="info" %}
`create_collection()` builds and caches a collection in memory but writes nothing to disk until `save()`. If a process exits first, the collection is gone. See [Snapshots & persistence](/working-with-data/snapshots-and-persistence.md).
{% endhint %}

## Platform tags and extensions

| OS                    | `platform_tag()` arch | `lib_ext` |
| --------------------- | --------------------- | --------- |
| macOS (Apple Silicon) | `macos-arm64`         | `dylib`   |
| Linux x86-64          | `linux-x86_64`        | `so`      |
| Linux ARM64           | `linux-arm64`         | `so`      |
| Windows               | (via WSL2)            | `dll`     |

## See also

* [Environment variables](/operations/environment-variables.md) — `TELYS_HOME` and `TELYS_MEMORY_PATH`.
* [Supported platforms](/operations/supported-platforms.md) — which `platform_tag()` targets ship a runtime.
* [Verify the runtime signature](/security/runtime-signature-verification.md) — checking the manifest and hashes.
* [Uninstall Telys](/operations/uninstalling.md) — removing this tree cleanly.


---

# 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/operations/on-disk-layout.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.