AGENTS.md · keploy/keploy

Sections

1. What this project is
2. Build, run, lint, test
3. Key commands (quick user-facing recap)
4. The on-disk format (for matching against reports in scripts)
5. Conventions
6. CI at a glance
7. Where to look first for common changes

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

Practical reference for agents working in `keploy/keploy`. Everything here is
grounded in the current state of the repo — if something below conflicts with
what you see on disk, trust the disk and update this file.

## What this project is

Keploy is a backend testing tool that records real API + dependency traffic
from a running application and replays it as deterministic tests with mocks.
It intercepts traffic at the network layer using eBPF (Linux) and a userspace
proxy (macOS/Windows), so apps don't need an SDK or code changes. The binary
is a single Go CLI: `keploy`.

- Go module: `go.keploy.io/server/v3`
- Primary entry point: `main.go` → `cli.Root(...)` in `cli/root.go`

## Build, run, lint, test

### Build the binary

```bash
# Standard build (what CI calls "build-no-race")
go build -tags=viper_bind_struct -o keploy .

# Race-enabled build (what CI calls "build" — used as the default in CI matrices)
CGO_ENABLED=1 go build -race -tags=viper_bind_struct -o keploy .
```

The `viper_bind_struct` build tag is required — leaving it off will cause
config fields not to bind correctly at runtime.

Version / Sentry DSN / server URL / GitHub client ID are injected via
`-ldflags` (see `Dockerfile` and `goreleaser.yaml`). For local development
the default `version` is `3-dev`.

### Run locally

Platform support is not uniform — it's gated by how the agent can
intercept traffic on each OS:

| Platform                  | Native binary (app runs on host)                                                                             | Keploy-in-Docker (app runs in Docker) |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| **Linux** (x86_64, arm64) | ✅ Supported — uses eBPF (`pkg/agent/hooks/linux/`). Requires root.                                          | ✅ Supported                          |
| **Windows** (x86-64)      | ❌ Falls through to the `others` stub in THIS build. Native Windows interception is userspace (no driver, no Administrator) and ships in the Community/Enterprise build, not here. | ✅ Supported                          |
| **Windows** (arm64)       | ❌ Same `others` stub, in every build — there is no native Windows/arm64 backend anywhere. | ✅ Supported                          |
| **macOS** (arm64 only — Apple Silicon) | ❌ Same `others` stub in THIS build. Native macOS interception is userspace and ships in the Community/Enterprise build. The CLI is not built for Intel Macs at all; use Docker or Lima there. | ✅ Supported (only option)            |

- This table is about **this repository's build**, which intercepts with eBPF
  and therefore records a natively-running app on Linux only.
  `DefaultNativeCommandSupported` in `cli/provider/hooks.go` encodes exactly
  that: `goos == "linux"`.
- Keploy as a **product** does record natively on macOS and Windows. Those
  userspace backends live in the Community/Enterprise build
  (`keploy/enterprise`), which widens the predicate above from its own
  `init()` via `RegisterNativeCommandSupport`. `keploy.sh` installs that build
  by default and `--oss` selects this one, so "keploy cannot run natively on
  macOS" is wrong — "this build cannot" is right. The refusal in
  `cli/provider/cmd.go` says it that way, naming the editions that can.
- With **this** build on **macOS** you must therefore:
  1. Build the keploy Docker image: `sudo docker image build -t ghcr.io/keploy/keploy:v3-dev .`
  2. Run your application inside Docker (usually via `docker compose`).
  3. Run keploy as that Docker image, which attaches to the app container.
     This is why `prepare_and_run_macos.yml` only calls `golang_docker_macos.yml`
     — there's no macOS-native equivalent here.
- On **Linux** you can pick either — native (with `sudo`) or via the
  Docker image. CI exercises both (`golang_linux.yml` + `golang_docker.yml`).
- The macOS binary this repo releases is **arm64 only** (Apple Silicon):
  macOS 27 drops Intel support, so no darwin/amd64 build is produced.

**Native Linux run:**

```bash
sudo ./keploy record -c "<your app cmd>"
sudo ./keploy test   -c "<your app cmd>" --delay 10
```

If you pass a `docker`/`docker compose` command as `-c` without sudo on
Linux, `main.go` detects that in `utils.ShouldReexecWithSudo()` and
`syscall.Exec`s itself under `sudo -E` (see `utils/reexec_linux.go`). On
macOS and Windows the same helper is a no-op — `reexec_darwin.go` and
`reexec_windows.go` both short-circuit to `false`, since those platforms
rely on the active Docker context / Docker Desktop.

### Docker

```bash
sudo docker image build -t ghcr.io/keploy/keploy:v3-dev .
```

`ghcr.io/keploy/keploy:v3-dev` is the tag CI produces for dev builds and the
one the samples expect.

### Lint

Linter is `golangci-lint` with config schema v2, at `.golangci.yml`:

- Enabled linters: `govet`, `staticcheck`, `errcheck`, `ineffassign`, `unused`
- Formatters: `gofmt`, `goimports`
- Generated files (Go's `// Code generated ... DO NOT EDIT.` header, such as the eBPF Go files) are not linted; no path is excluded.
- CI lints the Linux build of the root module: files built only for Windows or macOS, files behind a build tag such as `composelib`, and the lanes' own Go modules under `.github/` are not linted.
- In what it lints, CI fails on any issue on a line your change adds or edits. Issues already on lines you leave alone are not reported: the code base still holds older ones.

Check what CI checks (on Linux, from your branch, with `origin/main` fetched):

```bash
golangci-lint run --new-from-merge-base=origin/main
```

A bare `golangci-lint run` also lists the older issues.

### Commit hygiene

- `.pre-commit-config.yaml` wires `commitizen` (Conventional Commits).
- `.cz.toml` pins the convention to `cz_conventional_commits`. Use types
  like `feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`.
- Every commit needs a description body (blank line, then a paragraph
  explaining what changed and why).
- Sign off every commit with `git commit -s` — this appends a
  `Signed-off-by: <user.name> <user.email>` trailer using the values from
  the effective git config (system → `~/.gitconfig` → `.git/config`). Do
  not hand-construct the trailer; let git read the identity from config so
  it matches the author.

When opening PRs or issues — customer-data hygiene, PR body template, which
files not to touch — see the **`keploy-pr-workflow` skill**
(`.claude/skills/keploy-pr-workflow/SKILL.md`). Don't paste real traces,
tokens, internal hostnames, or production logs into PRs, issues, tests, or
committed fixtures.

## Key commands (quick user-facing recap)

| Command                      | Package                          | What it does                                                                     |
| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
| `keploy record -c "<cmd>"`   | `pkg/service/record`             | Runs the app, captures dependency traffic into `./keploy/test-set-*`             |
| `keploy test -c "<cmd>"`     | `pkg/service/replay`             | Replays recorded calls, mocks dependencies, writes `./keploy/reports/test-run-*` |
| `keploy rerecord -c "<cmd>"` | `pkg/service/orchestrator`       | Re-records against new code to pick up accepted changes                          |
| `keploy normalize`           | `pkg/service/tools`              | Accepts newly-observed responses into the golden test cases                      |
| `keploy sanitize`            | `pkg/service/tools`              | Scrubs secrets using `custom_gitleaks_rules.toml` + built-in rules               |
| `keploy templatize`          | `pkg/service/tools`              | Replaces dynamic values with templates in test sets                              |
| `keploy config --generate`   | `cli/config.go`                  | Writes `keploy.yml` with only the settings that DIFFER from the defaults          |
| `keploy config defaults`     | `cli/config.go`                  | Prints every setting and its default (`-o FILE` saves them)                      |
| `keploy contract ...`        | `pkg/service/contract`           | OpenAPI contract generation / testing                                            |
| `keploy diff <r1> <r2>`      | `pkg/service/diff`               | Diff two test runs                                                               |
| `keploy report`              | `pkg/service/report`             | Summarize a previous test run                                                    |
| `keploy export` / `import`   | `cli/export.go`, `cli/import.go` | Move test-sets between repos                                                     |
| `keploy update`              | `cli/update.go`                  | Self-update the binary                                                           |
| `keploy ca clean`            | `cli/ca.go`                      | Remove the retired static MITM CA (matched by fingerprint) from this host's trust store |
| `keploy agent`               | `cli/agent.go`                   | Internal — used by the Docker image entrypoint                                   |

Note: `keploy gen` (`pkg/service/utgen`, LLM unit-test generation) has its CLI
registration commented out in `cli/utgen.go` — the implementation exists but
the command isn't wired. Don't document it as user-facing.

`keploy --help` is authoritative; if you add, rename, or disable a command,
update this table in the same commit. Spin up a subagent to walk the `cli/`
directory if you need the full flag list for a specific command.

When a change alters user-visible behavior (new flag, changed default, new
command, new config field), the docs at `keploy/docs` may need updating — see