> 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

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](/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` to <eng@thyn.ai>.

</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="/pages/8ZuBgRkr29CUHhibOPXT">/pages/8ZuBgRkr29CUHhibOPXT</a></td></tr><tr><td><strong>Python version support</strong></td><td>Which Python versions the SDK and runtime target.</td><td><a href="/pages/yVB6wMEurT1jRXgd61kU">/pages/yVB6wMEurT1jRXgd61kU</a></td></tr></tbody></table>

Next: [Supported platforms](/operations/supported-platforms.md)


---

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