> 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

Reference map of everything Telys stores under $TELYS\_HOME — credentials, the verified runtime, and per-collection files.

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, `lexical`, 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](https://docs.telys.ai/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](https://docs.telys.ai/operations/environment-variables.md) — `TELYS_HOME` and `TELYS_MEMORY_PATH`.
* [Supported platforms](https://docs.telys.ai/operations/supported-platforms.md) — which `platform_tag()` targets ship a runtime.
* [Verify the runtime signature](https://docs.telys.ai/security/runtime-signature-verification.md) — checking the manifest and hashes.
* [Uninstall Telys](https://docs.telys.ai/operations/uninstalling.md) — removing this tree cleanly.
