> 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/troubleshooting/platform-specific.md).

# Platform-specific

Fix platform-specific issues — macOS Gatekeeper and PATH for GUI clients, experimental Linux arm64, Windows via WSL2, and unsupported Intel Mac.

The `telys` SDK is pure Python and runs anywhere Python 3.10+ does, but the **signed runtime** is a native binary installed per platform. Its platform tag is `<os>-<arch>` (for example `macos-arm64`, `linux-x86_64`). Supported targets are `macos-arm64`, `linux-x86_64`, and `linux-arm64` (experimental). Windows runs through WSL2; Intel macOS is not yet supported. The entries below cover the quirks of each.

{% hint style="info" %}
Check your resolved target with `telys runtime status`. A runtime installed for a different arch than you expected is usually the whole problem.
{% endhint %}

## Issues and fixes

<details>

<summary>macOS: Gatekeeper blocks the runtime, or a GUI client can't find <code>telys</code></summary>

Two macOS quirks show up together. Gatekeeper may quarantine a downloaded native library. And GUI apps (Claude Desktop, Cursor) launch from a minimal environment without your shell `PATH`, so a bare `telys` isn't found.

**Cause:** a quarantined runtime artifact, and/or a GUI client that can't resolve `telys`.

**Fix:** use the signed download path (`telys runtime install`) to fetch artifacts cleanly, then verify. For GUI clients, use the absolute path from `which telys`.

```bash
telys runtime install        # fetch the signed runtime for macos-arm64
telys runtime verify         # confirm signature + license

which telys                  # absolute path for GUI MCP clients
telys mcp install            # writes client config with the resolved absolute path
```

If macOS quarantined an offline bundle, re-fetch with `telys runtime install` rather than stripping attributes by hand — the artifact's hash must match the signed manifest.

Next: [MCP client won't connect](https://docs.telys.ai/troubleshooting/mcp-client.md)

</details>

<details>

<summary>Linux arm64 is experimental</summary>

`linux-arm64` is supported but marked **experimental** — best-effort, with rougher edges than `linux-x86_64`.

**Cause:** you're on `linux-arm64` and hit behavior that doesn't appear on x86\_64.

**Fix:** verify the install carefully, and prefer `linux-x86_64` for production if you can. Confirm the runtime resolved to the arm64 target.

```bash
telys runtime status         # confirm the platform tag is linux-arm64
telys runtime verify
```

Report `linux-arm64` bugs with the output of `telys version` and `telys runtime status` via the [contact form](https://telys.ai/contact).

</details>

<details>

<summary>Windows: run Telys under WSL2</summary>

There is no native Windows runtime. Windows is supported via **WSL2**, where Telys runs as a normal Linux install (`linux-x86_64`).

**Cause:** you tried to install the runtime on native Windows.

**Fix:** install Telys inside a WSL2 Linux distribution and run everything there.

```bash
# Inside a WSL2 shell (e.g. Ubuntu):
pipx install telys
telys login
telys runtime status         # linux-x86_64 inside WSL2
```

Keep your memory store on the WSL2 filesystem (for example `~/.telys`), not a Windows-mounted path, for correctness and speed.

</details>

<details>

<summary>Intel Mac (x86_64 macOS) is not yet supported</summary>

The runtime does not ship for Intel macOS. Only `macos-arm64` (Apple Silicon) is supported on macOS today.

**Cause:** you're on an Intel Mac (`macos-x86_64`), which has no runtime build.

**Fix:** run Telys on Apple Silicon or a supported Linux host. The SDK imports and `telys version` prints, but any collection operation raises `RuntimeNotInstalled` because there's no runtime for this target.

```bash
telys version                # prints — SDK is fine
telys runtime status         # exits non-zero — no runtime for macos-x86_64
```

Track platform support on the supported-platforms page.

</details>

## Next steps

The supported-platforms reference is the canonical matrix of targets, arch tags, and support status.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Supported platforms</strong></td><td>The full OS/arch matrix and support status.</td><td><a href="https://docs.telys.ai/operations/supported-platforms.md">Supported platforms</a></td></tr><tr><td><strong>Python version support</strong></td><td>Which Python versions the SDK and runtime target.</td><td><a href="https://docs.telys.ai/operations/python-version-support.md">Python support</a></td></tr></tbody></table>

Next: [Supported platforms](https://docs.telys.ai/operations/supported-platforms.md)
