Skip to content

docs: document native macOS and Windows support #900

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 4 commits into from
Aug 24, 2026
Merged

docs: document native macOS and Windows support #900

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
213f57e
docs: document native macOS and Windows support
slayerjain Aug 22, 2026
6a6cca0
docs: drop the Administrator requirement for native Windows (#901)
slayerjain Aug 23, 2026
c0efcf2
docs: format macos.md so the prettier check passes
slayerjain Aug 23, 2026
dcc4169
ci: make the prettier check use the version it declares
slayerjain Aug 23, 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
19 changes: 14 additions & 5 deletions .github/workflows/prettify_code.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,19 @@ jobs:
echo "has_files=false" >> $GITHUB_OUTPUT
fi

# Prettier is invoked directly rather than through
# creyD/prettier_action@v4.6, which accepts a prettier_version input but
# does not honour it: with 2.8.8 declared, the action installed 3.9.6
# ("The following package was not found and will be installed:
# prettier@3.9.6"). So CI silently enforced a different formatting
# contract than CONTRIBUTING and .prettierrc.json describe, and the two
# could drift apart without anyone noticing — a file formatted by hand to
# match the documented version could fail here, and vice versa.
#
# `npx prettier@<version>` pins what actually runs, so the version in this
# file is the version that checks the code. 2.8.8 is kept because it is
# what the repository is formatted with; 3.x reflows markdown differently
# and moving to it is a deliberate migration, not a CI detail.
- name: Check code formatting
if: steps.changed-files.outputs.has_files == 'true'
uses: creyD/prettier_action@v4.6
with:
prettier_version: 2.8.8
prettier_options: --check ${{ steps.changed-files.outputs.files }}
dry: true
run: npx --yes prettier@2.8.8 --check ${{ steps.changed-files.outputs.files }}
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** | [Guide](/keploy-explained/mac-linux.md) | [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** | [Guide](/keploy-explained/windows-wsl.md) | [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 (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 |

On macOS and Windows, additional tools are required for Keploy due to the lack of native eBPF support.
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.
52 changes: 46 additions & 6 deletions 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 @@ -2,7 +2,7 @@
id: macos-installation
title: Installing Keploy on macOS
sidebar_label: macOS Installation
description: A guide to installing Keploy on macOS using Lima or Docker.
description: A guide to running Keploy on macOS — natively, or with Lima or Docker.
tags:
- installation
keywords:
Expand All @@ -15,15 +15,55 @@ keywords:

# Installing Keploy on macOS

Keploy uses eBPF to intercept API calls on network layer and generates test cases and mocks/stubs. Keploy does not natively support macOS. However, you can still run it using **Lima** or **Docker**.
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.

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.

👉 **Choose your preferred method:**

- [Option 1: Install Keploy with Lima](#option-1-install-keploy-with-lima)
- [Option 1: Run Keploy natively (recommended)](#option-1-run-keploy-natively)

- [Option 2: Install Keploy with Lima](#option-2-install-keploy-with-lima)

- [Option 3: Install Keploy with Docker](#option-3-install-keploy-with-docker)

## Option 1: Run Keploy natively

1. **Install Keploy**

```bash
curl --silent -O -L https://keploy.io/install.sh && source install.sh
```

2. **Record your app** — pass the command that starts it, exactly as you run it yourself:

```bash
keploy record -c "<your app command>"
```

For example, a Go binary, a Node server, or a Python app:

```bash
keploy record -c "./myapp" # Go
keploy record -c "node server.js" # Node.js
keploy record -c "python app.py" # Python
```

3. **Replay the recorded tests**:

```bash
keploy test -c "<your app command>" --delay 10
```

:::note Good to know

- **No password prompt.** Native macOS interception needs no privileges, so `keploy record`/`test` do not ask for `sudo`.
- **Run the real executable, not a launcher.** macOS strips the interception from `npm start`, a `make` recipe, or a wrapper shell script (it is dropped when the OS runs a protected system binary). Run the app's actual command — `node server.js` rather than `npm start`, or build first and run the binary. Keploy warns you if it never got loaded.
- **Go HTTPS on macOS.** Go verifies TLS through the macOS Security framework; Keploy makes its interception CA trusted for your app's process only, so recording an HTTPS Go app works without touching your system keychain. Apps that pin a certificate (an explicit root pool) are the exception.

- [Option 2: Install Keploy with Docker](#option-2-install-keploy-with-docker)
:::

## Option 1: Install Keploy with Lima
## Option 2: Install Keploy with Lima

1. **Check if Lima is installed**
If you already have Lima, Go to Step 6.
Expand Down Expand Up @@ -74,7 +114,7 @@ Begin recording your API calls and automatically generate test cases with Keploy

---

## Option 2: Install Keploy with Docker
## Option 3: Install Keploy with Docker

1. **Make sure Docker is installed**
You’ll need Docker Desktop running on macOS.
Expand Down
57 changes: 51 additions & 6 deletions 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 @@ -2,7 +2,7 @@
id: windows-installation
title: Running Keploy on Windows
sidebar_label: Windows Installation
description: "Install Keploy on Windows using WSL or Docker — step-by-step guide for eBPF-based API test generation on Windows."
description: "Install Keploy on Windows — natively with no Administrator needed, or with WSL or Docker."
tags:
- windows
- ebpf
Expand All @@ -17,21 +17,66 @@ keywords:

# Installing Keploy on Windows

Keploy uses eBPF to intercept API calls on network layer and generates test cases and mocks/stubs. Keploy does not natively support Windows. However, you can still run it using **Wsl** or **Docker**.
Keploy runs **natively on Windows** — you can record and replay an app that runs directly on Windows, with no WSL and no Docker. There is no eBPF on Windows, so Keploy instruments the application it starts and intercepts its network calls in user space. No driver loads, nothing is installed system-wide, and **you do not need Administrator**.

Native Windows support covers apps in **Go, Node.js, Python and Java**. WSL and Docker remain available if you prefer them.

👉 **Choose your preferred method:**

- [Option 1: Install Keploy with WSL](#option-1-install-keploy-with-wsl)
- [Option 1: Run Keploy natively (recommended)](#option-1-run-keploy-natively)

- [Option 2: Install Keploy with WSL](#option-2-install-keploy-with-wsl)

- [Option 3: Install Keploy with Docker](#option-3-install-keploy-with-docker)

## Option 1: Run Keploy natively

1. **Install Keploy** — download the Windows build from the [releases page](https://github.com/keploy/keploy/releases) (or your Keploy distribution) and put `keploy.exe` on your `PATH`.

2. **Open a terminal.** An ordinary PowerShell or Terminal window is enough — Keploy does not need to run elevated.

3. **Record your app** — pass the command that starts it:

```powershell
keploy record -c "<your app command>"
```

For example:

```powershell
keploy record -c ".\myapp.exe" # Go
keploy record -c "node server.js" # Node.js
keploy record -c "python app.py" # Python
```

4. **Replay the recorded tests**:

```powershell
keploy test -c "<your app command>" --delay 10
```

:::note

Native Windows support is **x86‑64 only**, and the application under test must be 64-bit. On Windows/ARM, use WSL or Docker.

- [Option 2: Install Keploy with Docker](#option-2-install-keploy-with-docker)
:::

## Option 1: Install Keploy with WSL
:::note

Keploy instruments the application **it starts**, so launch your app through `keploy record -c` or `keploy test -c` rather than starting it yourself and pointing Keploy at a running process.

Keploy intercepts TCP — HTTP, HTTPS, gRPC, and database and cache protocols — and resolves hostnames through the application's resolver, so a dependency that no longer exists is still answered from its Mock during a replay. Traffic an application sends over UDP is not recorded.

:::

## Option 2: Install Keploy with WSL

If you already have WSL, Go to Step 2.

1. **Enable WSL**

Make sure you’re on:

- **Windows 10** (version 2004 or later, build 19041+)
- **Windows 11**

Expand Down Expand Up @@ -67,7 +112,7 @@ Begin recording your API calls and automatically generate test cases with Keploy

---

## Option 2: Install Keploy with Docker
## Option 3: Install Keploy with Docker

1. **Make sure Docker is installed**
You’ll need **Docker Desktop** running on Windows.
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-4.0.0/keploy-explained/dev-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ curl --silent -O -L https://keploy.io/install.sh && source install.sh --oss
<br />

:::info
Keploy does not natively support macOS. You can run it using **Lima** or **Docker**.
Keploy runs natively on macOS (Go, Node, Python and Java apps). You can also run it using **Lima** or **Docker**.
:::

<Tabs>
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-4.0.0/server/installation_tabs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,7 @@ Use "keploy [command] --help" for more information about a command.
<TabItem value="macos" label="macOS">
<br />
:::info
Keploy does not natively support macOS. However, you can run it using **Lima** or **Docker**.
Keploy runs natively on macOS (Go, Node, Python and Java apps). You can also run it using **Lima** or **Docker**.
:::

👉 **Choose your preferred method:**
Expand Down
Loading