Skip to content

docs(macos): Apple Silicon only, and stop saying Keploy cannot run natively on macOS #911

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slayerjain merged 6 commits into from
Sep 22, 2026
Merged

docs(macos): Apple Silicon only, and stop saying Keploy cannot run natively on macOS #911

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7903f6d
docs(macos): say the native CLI is Apple Silicon only, and route Inte…
slayerjain Sep 22, 2026
b0c706f
docs: stop saying Keploy cannot run natively on macOS — the Community…
slayerjain Sep 22, 2026
8783bb6
style(docs): run prettier on the platforms table
slayerjain Sep 22, 2026
4645e5a
docs: name the Community Edition wherever native macOS/Windows is men…
slayerjain Sep 22, 2026
967c414
docs: it is just "keploy" — drop the edition qualifiers
slayerjain Sep 22, 2026
6a516ba
docs(contribution-guide): install keploy, not an "open-source build"
slayerjain Sep 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/llms-full-root.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ keploy version
```

### macOS
Requires Docker Desktop or Colima. Install via the same script or Homebrew.
Runs natively on Apple Silicon (arm64) only — install via the same script or `brew install keploy/tap/keploy`; no Docker needed (userspace interception, no root). Both refuse to install on an Intel Mac: there, run Keploy inside a Lima VM (https://keploy.io/docs/installation/macos-installation/#option-2-install-keploy-with-lima). The Docker Desktop/Colima route still runs the native CLI on the host, so it is also Apple Silicon only.

### Windows
Requires WSL2 (Windows Subsystem for Linux). Install within the WSL2 environment using the Linux installation method.
Expand All @@ -108,7 +108,7 @@ Keploy can run as a Docker container alongside your application using Docker Com

### Platform Requirements
- Linux: Kernel version 5.15+ recommended for eBPF support
- macOS: Docker Desktop or Colima required (eBPF runs inside the Linux VM)
- macOS: Apple Silicon (arm64) for the native CLI; Intel Macs run Keploy in a Lima VM (Linux build inside the VM)
- Windows: WSL2 with a compatible Linux kernel

---
Expand Down
4 changes: 2 additions & 2 deletions versioned_docs/version-4.0.0/concepts/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Use "keploy [command] --help" for more information about a command.

#### On macOS/Windows

Note : Keploy is not supported natively on MacOS and Windows, so you can follow the below method to run with docker
Note : With this method your application and Keploy's agent run in Docker, but the `keploy` CLI installed below — which starts them both — runs on your machine. On macOS that CLI is the native build, which is Apple Silicon (arm64) only — on an Intel Mac, run Keploy with [Lima](/docs/installation/macos-installation/#option-2-install-keploy-with-lima) instead.

1. Open up a terminal window.

Expand Down Expand Up @@ -151,7 +151,7 @@ sudo mkdir -p /usr/local/bin && sudo mv /tmp/keploy /usr/local/bin/keploy

```

> Note: Keploy is not supported on MacOS natively.
> Note: On macOS, Keploy's native CLI is Apple Silicon (arm64) only — see [Installing Keploy on macOS](/docs/installation/macos-installation/). On an Intel Mac, run Keploy with [Lima](/docs/installation/macos-installation/#option-2-install-keploy-with-lima), which installs the Linux build above inside the VM.

**_Setting up the Docker Desktop for WSL 2_**

Expand Down
12 changes: 6 additions & 6 deletions versioned_docs/version-4.0.0/concepts/platform-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ keywords:
Below is a table summarizing the tools needed for both native and Docker installations of Keploy on macOS, Windows, and
Linux:

| Operating System | Without Docker | Docker Installation | Prerequisites |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://www.pngplay.com/wp-content/uploads/3/Apple-Logo-Transparent-Images.png" width="15" height="15" alt="macOS" /> **macOS** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> Native (Go, Node, Python, Java) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above <br/> - Ensure that Lima is installed on your machine if you prefer to try without Docker. |
| <img src="https://upload.wikimedia.org/wikipedia/commons/5/5f/Windows_logo_-_2012.svg" width="15" height="15" alt="Windows" /> **Windows** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> Native, x86‑64 (Go, Node, Python, Java) | [Guide](/server/install/) | - Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install#install-wsl-command) `wsl --install` <br/> - Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 <br/> - Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide |
| <img src="https://th.bing.com/th/id/R.7802b52b7916c00014450891496fe04a?rik=r8GZM4o2Ch1tHQ&riu=http%3a%2f%2f1000logos.net%2fwp-content%2fuploads%2f2017%2f03%2fLINUX-LOGO.png&ehk=5m0lBvAd%2bzhvGg%2fu4i3%2f4EEHhF4N0PuzR%2fBmC1lFzfw%3d&risl=&pid=ImgRaw&r=0" width="10" height="10" alt="Linux" /> **Linux** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> | Linux kernel 5.15 or higher |
| Operating System | Without Docker | Docker Installation | Prerequisites |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://www.pngplay.com/wp-content/uploads/3/Apple-Logo-Transparent-Images.png" width="15" height="15" alt="macOS" /> **macOS** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> Native, Apple Silicon (Go, Node, Python, Java) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above <br/> - Ensure that Lima is installed on your machine if you prefer to try without Docker. |
| <img src="https://upload.wikimedia.org/wikipedia/commons/5/5f/Windows_logo_-_2012.svg" width="15" height="15" alt="Windows" /> **Windows** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> Native, x86‑64 (Go, Node, Python, Java) | [Guide](/server/install/) | - Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install#install-wsl-command) `wsl --install` <br/> - Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 <br/> - Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide |
| <img src="https://th.bing.com/th/id/R.7802b52b7916c00014450891496fe04a?rik=r8GZM4o2Ch1tHQ&riu=http%3a%2f%2f1000logos.net%2fwp-content%2fuploads%2f2017%2f03%2fLINUX-LOGO.png&ehk=5m0lBvAd%2bzhvGg%2fu4i3%2f4EEHhF4N0PuzR%2fBmC1lFzfw%3d&risl=&pid=ImgRaw&r=0" width="10" height="10" alt="Linux" /> **Linux** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> | <img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Green_tick_pointed.svg" width="20" height="20" alt="Supported" /> | Linux kernel 5.15 or higher |

Keploy runs natively on macOS and Windows (x86‑64) — neither has eBPF, so it intercepts traffic in userspace on both, and neither needs `sudo` or Administrator. Docker, Lima (macOS) and WSL (Windows) remain supported alternatives, and are still the route on Windows/ARM.
Keploy runs natively on macOS (Apple Silicon / arm64) and Windows (x86‑64) — neither has eBPF, so it intercepts traffic in userspace on both, and neither needs `sudo` or Administrator. Docker, Lima (macOS) and WSL (Windows) remain supported alternatives, and are still the route on Windows/ARM. On an Intel Mac use Lima: the Docker route on macOS still runs the native CLI on the host, so it is Apple Silicon only too.
14 changes: 13 additions & 1 deletion versioned_docs/version-4.0.0/installation/macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ keywords:

# Installing Keploy on macOS

Keploy now runs **natively on macOS** — you can record and replay an app that runs directly on your Mac, with no Lima VM and no Docker. Native macOS support intercepts traffic in userspace (there is no eBPF on macOS), so it needs no root and installs nothing system-wide.
Keploy now runs **natively on macOS** (Apple Silicon) — you can record and replay an app that runs directly on your Mac, with no Lima VM and no Docker. Native macOS support intercepts traffic in userspace (there is no eBPF on macOS), so it needs no root and installs nothing system-wide.

Native macOS support covers **Go, Node.js, Python and Java** apps, including their HTTPS traffic. Docker and Lima remain available if you prefer to run your app in a container.

Expand All @@ -41,6 +41,12 @@ A free account is enough to record and replay. Free-tier runs are subject to a u

## Option 1: Run Keploy natively

:::note Apple Silicon only

The native macOS build is **Apple Silicon (arm64) only**. On an Intel Mac the installer, the Homebrew formula and `keploy update` refuse to install rather than fetch a binary that cannot run there. If one of them sent you here, use [Option 2 (Lima)](#option-2-install-keploy-with-lima), which installs the Linux build inside the VM. [Option 3 (Docker)](#option-3-install-keploy-with-docker) is not an Intel route either: it starts your app and Keploy's agent in containers, but the `keploy` CLI that drives it is the same native build running on your Mac.

:::

1. **Install Keploy**

```bash
Expand Down Expand Up @@ -128,6 +134,12 @@ Begin recording your API calls and automatically generate test cases with Keploy

## Option 3: Install Keploy with Docker

:::note Also Apple Silicon only

With this option your application and Keploy's agent run in containers, but the `keploy` CLI installed in step 3 — which starts them both — is the native macOS build, which is Apple Silicon (arm64) only. On an Intel Mac use [Option 2 (Lima)](#option-2-install-keploy-with-lima) instead.

:::

1. **Make sure Docker is installed**
You’ll need Docker Desktop running on macOS.

Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-4.0.0/installation/windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ A free account is enough to record and replay. Free-tier runs are subject to a u

Open a new terminal so the updated `Path` takes effect, then check it with `keploy --version`.

**Use the Community build for native Windows.** Native Windows interception ships in the Community build that both routes above install. Its download is named `enterprise_windows_amd64.exe` for historical reasons — a free account is all you need. The `keploy_windows_amd64` asset on the [GitHub releases page](https://github.com/keploy/keploy/releases) is a different, OSS build that intercepts with eBPF and so refuses a native Windows run with _"not supported by this build of Keploy"_. Use that asset only if you are running Keploy inside Docker.
**Use the download above, not the GitHub release asset.** The Windows binary is named `enterprise_windows_amd64.exe` for historical reasons — a free account is all you need. The `keploy_windows_amd64` asset on the [GitHub releases page](https://github.com/keploy/keploy/releases) is a different build that intercepts with eBPF and so refuses a native Windows run with _"not supported by this build of Keploy"_; it is only for running Keploy inside Docker.

**If Windows blocks the download.** The Windows build is not yet code-signed, so SmartScreen may show "Windows protected your PC" on first run. The `Unblock-File` line above clears the download marker; if you fetched the binary another way, right-click it, choose **Properties**, and tick **Unblock**.

Expand Down
Loading
Loading