> 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/environment-variables.md).

# Environment variables

Reference for every Telys environment variable — defaults, effects, precedence, and which commands read them.

Telys reads all configuration from the environment. Every variable has a working default, so a standard `pipx install telys` → `telys login` flow needs none of them. Set a variable only to override a location, force a behavior, or point at a non-default endpoint (mirrors, CI, custom install roots).

Variables are read at process start. Export them in your shell profile, process manager, or MCP client `env` block.

## Full variable table

| Variable                                             | Default                         | Effect                                                                                                                                                                              |
| ---------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TELYS_HOME`                                         | `~/.telys`                      | Root of all on-disk state (creds, runtime, default memory dir).                                                                                                                     |
| `TELYS_ACCOUNTS_URL`                                 | `https://accounts.thyn.ai`      | Identity portal used for device-code sign-in.                                                                                                                                       |
| `TELYS_API_URL`                                      | `https://api.telys.ai`          | Control plane for keys, device registration, and licenses.                                                                                                                          |
| `TELYS_PACKAGES_URL`                                 | `https://packages.telys.ai`     | Host that serves the signed runtime download.                                                                                                                                       |
| `TELYS_TOKEN`                                        | —                               | Control-plane auth token override (headless / CI).                                                                                                                                  |
| `TELYS_API_KEY`                                      | —                               | Telys API key override.                                                                                                                                                             |
| `TELYS_KERNEL`                                       | —                               | Force the native kernel library path. Highest priority.                                                                                                                             |
| `AME_KERNEL`                                         | —                               | Legacy kernel library path override (used if `TELYS_KERNEL` is unset).                                                                                                              |
| `TELYS_MEMORY_PATH`                                  | `~/.telys/memory`               | Memory directory used by the MCP server and `telys mem`.                                                                                                                            |
| `TELYS_MCP_WORKSPACE`                                | —                               | Repo root the MCP auto-indexer maps for `telys_index_repo` / `telys_repo_search`. When unset, callers must pass `path` per call. The `telys mcp --workspace` flag takes precedence. |
| `TELYS_RUNTIME`                                      | `""` (auto)                     | Force the runtime backend: `native` or `local`.                                                                                                                                     |
| `TELYS_LICENSE_ISSUER`                               | `https://license.algenta.ai`    | Expected license `iss` claim.                                                                                                                                                       |
| `TELYS_LICENSE_AUDIENCE`                             | `telys-runtime,algenta-runtime` | Accepted license `aud` values (comma-separated).                                                                                                                                    |
| `TELYS_RELEASE_PUBKEY` / `TELYS_RELEASE_PUBKEY_FILE` | embedded PEM                    | Override the release-manifest verification key (inline PEM / path to PEM).                                                                                                          |
| `TELYS_LICENSE_PUBKEY` / `TELYS_LICENSE_PUBKEY_FILE` | embedded PEM                    | Override the license verification key (inline PEM / path to PEM).                                                                                                                   |
| `TELYS_LICENSE`                                      | —                               | License token for `telys serve` (`--require-license`).                                                                                                                              |
| `TELYS_ACCESS_TOKEN`                                 | —                               | Bearer token for `telys serve` over TCP.                                                                                                                                            |

## Grouped by purpose

### On-disk state

`TELYS_HOME` relocates every file Telys writes: cached credentials, the verified runtime, and the default memory directory. `TELYS_MEMORY_PATH` overrides just the engine directory used by the MCP server and `telys mem`. `TELYS_MCP_WORKSPACE` sets the repo root the MCP auto-indexer maps (`telys_repo_search`); the `telys mcp --workspace` flag takes precedence over it.

```bash
export TELYS_HOME=/opt/telys
export TELYS_MEMORY_PATH=/data/telys-memory
export TELYS_MCP_WORKSPACE=/data/src/myrepo
```

{% hint style="info" %}
`TELYS_MEMORY_PATH` affects only the MCP server and `telys mem`. In Python, the path you pass to `Telys("/some/path")` is authoritative — neither variable applies. See [On-disk layout](https://docs.telys.ai/operations/on-disk-layout.md) for the full file tree.
{% endhint %}

### Identity & control plane

`telys login` and the control-plane API use three hosted endpoints. Override them to point at a mirror or staging environment; leave them unset in production.

| Variable             | Used by                                           |
| -------------------- | ------------------------------------------------- |
| `TELYS_ACCOUNTS_URL` | Device-code sign-in (browser flow).               |
| `TELYS_API_URL`      | Key issuance, device registration, license fetch. |
| `TELYS_PACKAGES_URL` | `telys runtime install` (hosted download).        |

`TELYS_TOKEN` and `TELYS_API_KEY` inject already-issued credentials so a process authenticates without an interactive login — the CI pattern.

```bash
export TELYS_TOKEN="$TELYS_TOKEN"      # control-plane auth token
export TELYS_API_KEY="$TELYS_API_KEY"  # Telys API key
```

### Runtime & kernel selection

`TELYS_RUNTIME` forces the backend `load_runtime()` returns: `native` loads the signed native runtime, `local` loads the local runtime, and the empty default lets Telys choose. Verified installs are native-only and fail closed.

The kernel-path variables select which native kernel library the embedders load. `TELYS_KERNEL` wins; `AME_KERNEL` is the legacy fallback, consulted only when `TELYS_KERNEL` is unset.

```bash
export TELYS_RUNTIME=native
export TELYS_KERNEL=/opt/telys/runtime/macos-arm64/libame_kernel.dylib
```

{% hint style="warning" %}
The `Algenta*` embedders require the native kernel and raise `ImportError` without it. Set a kernel path only when the auto-discovered library is in a non-standard location.
{% endhint %}

### License & signature verification

These back the offline verification API in `telys.verify` and license enforcement in `telys serve --require-license`. Defaults match the SDK constants (`DEFAULT_LICENSE_ISSUER`, `DEFAULT_LICENSE_AUDIENCES`); the public keys ship embedded in the wheel.

| Variable                         | Overrides                                       |
| -------------------------------- | ----------------------------------------------- |
| `TELYS_LICENSE_ISSUER`           | Expected `iss` claim on the license token.      |
| `TELYS_LICENSE_AUDIENCE`         | Accepted `aud` values (comma-separated list).   |
| `TELYS_RELEASE_PUBKEY` / `_FILE` | Key used to verify the signed runtime manifest. |
| `TELYS_LICENSE_PUBKEY` / `_FILE` | Key used to verify the license token.           |

For each key override, the plain variable holds an inline PEM string and the `_FILE` variant holds a path to a PEM file. Change these only for a private release channel with its own signing keys.

### Serving

`telys serve` reads two secrets from the environment to keep them out of shell history and process listings. `TELYS_ACCESS_TOKEN` is the bearer token required for TCP listeners (anonymous TCP is refused); `TELYS_LICENSE` supplies the token checked by `--require-license`.

```bash
export TELYS_ACCESS_TOKEN="$TELYS_ACCESS_TOKEN"
export TELYS_LICENSE="$TELYS_LICENSE"
telys serve --path ./memory --host 127.0.0.1 --port 8777 --require-license
```

## Precedence

* **Kernel path:** `TELYS_KERNEL` → `AME_KERNEL` → auto-discovery.
* **Runtime backend:** `TELYS_RUNTIME` (if set) → verified install (native) → local.
* **Verification keys:** `_FILE` and inline overrides replace the embedded PEMs; otherwise the wheel's keys are used.
* **`telys serve` secrets:** an explicit `--access-token` / `--license` flag beats the corresponding `TELYS_ACCESS_TOKEN` / `TELYS_LICENSE` variable.

## See also

* [Environment & exit codes](https://docs.telys.ai/cli/environment-and-exit-codes.md) — the same variables in CLI context.
* [On-disk layout](https://docs.telys.ai/operations/on-disk-layout.md) — what `TELYS_HOME` actually contains.
* [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md) — how the serve secrets are enforced.
* [The signed runtime & trust model](https://docs.telys.ai/understand-telys/signed-runtime-trust.md) — where the verification keys fit.
