From 213f57ecf0ca6418bac549f3d685cc4e980c2b03 Mon Sep 17 00:00:00 2001 From: Shubham Jain Date: Sat, 22 Aug 2026 10:27:06 +0530 Subject: [PATCH 1/4] docs: document native macOS and Windows support Keploy now runs natively on macOS (userspace interception, no eBPF, no privileges) and on Windows/x86-64 (the WinDivert driver), covering Go, Node, Python and Java apps. The docs still said "Keploy does not natively support macOS/Windows" and routed everyone to Lima, WSL or Docker. - installation/macos.md, installation/windows.md: add a native "Option 1" with record/replay steps, keeping Lima/WSL/Docker as alternatives. Note the macOS no-sudo behaviour, the launcher caveat (run the real executable, not `npm start`), and that Go HTTPS is handled without touching the keychain. - concepts/platform-requirements.md: mark macOS and Windows as natively supported in the "Without Docker" column, with the Windows/ARM and container routes still listed. - keploy-explained/dev-guide.md, server/installation_tabs.md: correct the "does not natively support macOS" statements. Signed-off-by: Shubham Jain --- .../concepts/platform-requirements.md | 6 +-- .../version-4.0.0/installation/macos.md | 54 ++++++++++++++++--- .../version-4.0.0/installation/windows.md | 50 ++++++++++++++--- .../keploy-explained/dev-guide.md | 2 +- .../version-4.0.0/server/installation_tabs.md | 2 +- 5 files changed, 97 insertions(+), 17 deletions(-) diff --git a/versioned_docs/version-4.0.0/concepts/platform-requirements.md b/versioned_docs/version-4.0.0/concepts/platform-requirements.md index 2871e9d4c1..ed6f8c5514 100644 --- a/versioned_docs/version-4.0.0/concepts/platform-requirements.md +++ b/versioned_docs/version-4.0.0/concepts/platform-requirements.md @@ -28,8 +28,8 @@ Linux: | Operating System | Without Docker | Docker Installation | Prerequisites | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| macOS **macOS** | [Guide](/keploy-explained/mac-linux.md) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above
- Ensure that Lima is installed on your machine if you prefer to try without Docker. | -| 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`
- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
- Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide | +| macOS **macOS** | Supported Native (Go, Node, Python, Java) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above
- Ensure that Lima is installed on your machine if you prefer to try without Docker. | +| Windows **Windows** | 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`
- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
- Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide | | Linux **Linux** | Supported | 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 — it intercepts traffic in userspace on macOS and with the WinDivert driver on Windows (x86‑64), since neither has eBPF. Docker, Lima (macOS) and WSL (Windows) remain supported alternatives, and are still the route on Windows/ARM. diff --git a/versioned_docs/version-4.0.0/installation/macos.md b/versioned_docs/version-4.0.0/installation/macos.md index d0fe68756b..3d0f54bb91 100644 --- a/versioned_docs/version-4.0.0/installation/macos.md +++ b/versioned_docs/version-4.0.0/installation/macos.md @@ -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: @@ -15,15 +15,57 @@ 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 "" + ``` + + 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 "" --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. @@ -74,7 +116,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. diff --git a/versioned_docs/version-4.0.0/installation/windows.md b/versioned_docs/version-4.0.0/installation/windows.md index 4e42c36e2f..1a27bdd2d0 100644 --- a/versioned_docs/version-4.0.0/installation/windows.md +++ b/versioned_docs/version-4.0.0/installation/windows.md @@ -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 the WinDivert driver, or with WSL or Docker." tags: - windows - ebpf @@ -17,15 +17,53 @@ 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. On Windows it intercepts traffic with the WinDivert network driver (there is no eBPF on Windows), which needs Administrator privileges. + +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 an Administrator terminal.** WinDivert loads a network driver, so `keploy` must run elevated (right-click PowerShell or Terminal → _Run as administrator_). + +3. **Record your app** — pass the command that starts it: + + ```powershell + keploy record -c "" + ``` + + 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 "" --delay 10 + ``` + +:::note + +Native Windows support is **x86‑64 only**. 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 +## Option 2: Install Keploy with WSL If you already have WSL, Go to Step 2. @@ -67,7 +105,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. diff --git a/versioned_docs/version-4.0.0/keploy-explained/dev-guide.md b/versioned_docs/version-4.0.0/keploy-explained/dev-guide.md index a4a6b6b79c..84ce8f3b06 100644 --- a/versioned_docs/version-4.0.0/keploy-explained/dev-guide.md +++ b/versioned_docs/version-4.0.0/keploy-explained/dev-guide.md @@ -199,7 +199,7 @@ curl --silent -O -L https://keploy.io/install.sh && source install.sh --oss
:::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**. ::: diff --git a/versioned_docs/version-4.0.0/server/installation_tabs.md b/versioned_docs/version-4.0.0/server/installation_tabs.md index 76b0c5ac39..aea2e6327f 100644 --- a/versioned_docs/version-4.0.0/server/installation_tabs.md +++ b/versioned_docs/version-4.0.0/server/installation_tabs.md @@ -230,7 +230,7 @@ Use "keploy [command] --help" for more information about a command.
:::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:** From 6a6cca04bcc9fe8b6a6f5adb0c17c7b65bfa2f38 Mon Sep 17 00:00:00 2001 From: Shubham Jain Date: Sun, 23 Aug 2026 13:14:52 +0530 Subject: [PATCH 2/4] docs: drop the Administrator requirement for native Windows (#901) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Native Windows interception used a kernel packet-filter driver, which could only load from an elevated terminal. Keploy now instruments the application it starts and intercepts its network calls in user space instead, so the driver — and the Administrator requirement with it — is gone. - installation/windows.md: drop the "open an Administrator terminal" step and the WinDivert explanation, and state the two limits that come with instrumenting the application rather than filtering packets: Keploy has to be the one that starts it, and UDP traffic is not recorded. Hostname resolution is covered, so a dependency that no longer exists is still answered from its Mock on a replay. - concepts/platform-requirements.md: macOS and Windows are both userspace now, and neither needs sudo or Administrator. The `wsl --install` steps keep their "as Administrator" note — that genuinely needs elevation and is unrelated. Blocked on keploy/keploy#4476, which removes the driver. Do not merge before it ships, or the page will describe behaviour users do not have yet. Signed-off-by: Shubham Jain --- .../concepts/platform-requirements.md | 12 ++++++------ .../version-4.0.0/installation/windows.md | 15 +++++++++++---- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/versioned_docs/version-4.0.0/concepts/platform-requirements.md b/versioned_docs/version-4.0.0/concepts/platform-requirements.md index ed6f8c5514..5810242f60 100644 --- a/versioned_docs/version-4.0.0/concepts/platform-requirements.md +++ b/versioned_docs/version-4.0.0/concepts/platform-requirements.md @@ -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 | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| macOS **macOS** | Supported Native (Go, Node, Python, Java) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above
- Ensure that Lima is installed on your machine if you prefer to try without Docker. | -| Windows **Windows** | 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`
- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
- Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide | -| Linux **Linux** | Supported | Supported | Linux kernel 5.15 or higher | +| Operating System | Without Docker | Docker Installation | Prerequisites | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| macOS **macOS** | Supported Native (Go, Node, Python, Java) | [Guide](/server/install/) | - Docker Desktop version must be 4.25.2 or above
- Ensure that Lima is installed on your machine if you prefer to try without Docker. | +| Windows **Windows** | 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`
- Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
- Ensure that Docker Desktop version 4.25.2 or above is installed if you are following the Docker installation guide | +| Linux **Linux** | Supported | Supported | Linux kernel 5.15 or higher | -Keploy runs natively on macOS and Windows — it intercepts traffic in userspace on macOS and with the WinDivert driver on Windows (x86‑64), since neither has eBPF. Docker, Lima (macOS) and WSL (Windows) remain supported alternatives, and are still the route on Windows/ARM. +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. diff --git a/versioned_docs/version-4.0.0/installation/windows.md b/versioned_docs/version-4.0.0/installation/windows.md index 1a27bdd2d0..30611beca6 100644 --- a/versioned_docs/version-4.0.0/installation/windows.md +++ b/versioned_docs/version-4.0.0/installation/windows.md @@ -2,7 +2,7 @@ id: windows-installation title: Running Keploy on Windows sidebar_label: Windows Installation -description: "Install Keploy on Windows — natively with the WinDivert driver, or with WSL or Docker." +description: "Install Keploy on Windows — natively with no Administrator needed, or with WSL or Docker." tags: - windows - ebpf @@ -17,7 +17,7 @@ keywords: # Installing Keploy on Windows -Keploy runs **natively on Windows** — you can record and replay an app that runs directly on Windows, with no WSL and no Docker. On Windows it intercepts traffic with the WinDivert network driver (there is no eBPF on Windows), which needs Administrator privileges. +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. @@ -33,7 +33,7 @@ Native Windows support covers apps in **Go, Node.js, Python and Java**. WSL and 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 an Administrator terminal.** WinDivert loads a network driver, so `keploy` must run elevated (right-click PowerShell or Terminal → _Run as administrator_). +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: @@ -57,11 +57,17 @@ Native Windows support covers apps in **Go, Node.js, Python and Java**. WSL and :::note -Native Windows support is **x86‑64 only**. On Windows/ARM, use WSL or Docker. +Native Windows support is **x86‑64 only**, and the application under test must be 64-bit. On Windows/ARM, use WSL or Docker. ::: +:::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 @@ -70,6 +76,7 @@ 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** From c0efcf2d93cb54c8a02e43724f76d3814578cbc1 Mon Sep 17 00:00:00 2001 From: Shubham Jain Date: Sun, 23 Aug 2026 13:22:41 +0530 Subject: [PATCH 3/4] docs: format macos.md so the prettier check passes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prettier lane fails on this PR because installation/macos.md carries two consecutive blank lines. Prettier collapses them, and the check runs over every file the PR touches, so the whole lane goes red on whitespace. Content is untouched — this is the output of `prettier --write` on that one file, and every file this PR changes now passes under both prettier 2.8.8 (the version .github/workflows/prettify_code.yml asks for) and 3.9.6 (the version the action actually installs). Signed-off-by: Shubham Jain --- versioned_docs/version-4.0.0/installation/macos.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versioned_docs/version-4.0.0/installation/macos.md b/versioned_docs/version-4.0.0/installation/macos.md index 3d0f54bb91..ed8f2db750 100644 --- a/versioned_docs/version-4.0.0/installation/macos.md +++ b/versioned_docs/version-4.0.0/installation/macos.md @@ -63,8 +63,6 @@ Native macOS support covers **Go, Node.js, Python and Java** apps, including the ::: - - ## Option 2: Install Keploy with Lima 1. **Check if Lima is installed** From dcc416917e4863366ffa59ee2f66b3ec84e279b0 Mon Sep 17 00:00:00 2001 From: Shubham Jain Date: Sun, 23 Aug 2026 13:27:12 +0530 Subject: [PATCH 4/4] ci: make the prettier check use the version it declares MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit prettify_code.yml passes prettier_version: 2.8.8 to creyD/prettier_action@v4.6, and the action ignores it — the run log reads "The following package was not found and will be installed: prettier@3.9.6". So the formatting contract CI enforced was not the one CONTRIBUTING and .prettierrc.json describe, and the two could drift apart silently: a file formatted to the documented version could fail the check, and a file the check accepts could be wrong by the documented version. Calling prettier directly removes the ambiguity — `npx prettier@2.8.8` runs 2.8.8 — and drops a third-party action from the path for a one-line command. 2.8.8 stays because it is what this repository is formatted with: across versioned_docs/version-4.0.0, 23 files diverge from 2.8.8 and 29 from 3.9.6. Moving to 3.x reflows markdown and is a deliberate migration, not something to inherit from an action's default. Signed-off-by: Shubham Jain --- .github/workflows/prettify_code.yml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/.github/workflows/prettify_code.yml b/.github/workflows/prettify_code.yml index ee4daa421d..333d0154c6 100644 --- a/.github/workflows/prettify_code.yml +++ b/.github/workflows/prettify_code.yml @@ -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@` 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 }}