> 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

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

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

{% 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](/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](/cli/environment-and-exit-codes.md) — the same variables in CLI context.
* [On-disk layout](/operations/on-disk-layout.md) — what `TELYS_HOME` actually contains.
* [Auth & network model](/self-hosting/auth-and-network.md) — how the serve secrets are enforced.
* [The signed runtime & trust model](/understand-telys/signed-runtime-trust.md) — where the verification keys fit.


---

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