---
title: "In-Cluster (Web) | Speedscale Docs"
description: "Use proxymock web to connect to your Kubernetes cluster, enable capture, and run replays in cluster with live results."
canonical: "https://docs.speedscale.com/proxymock/getting-started/quickstart/in-cluster/"
---

[Documentation index](https://docs.speedscale.com/proxymock/llms.txt) | [Markdown](https://docs.speedscale.com/proxymock/getting-started/quickstart/in-cluster/index.md) | [Canonical page](https://docs.speedscale.com/proxymock/getting-started/quickstart/in-cluster/)

# In-Cluster (Web)

Use proxymock web to work directly against your Kubernetes cluster. You can:

*   Enable eBPF capture on a workload to record real in-cluster traffic
*   Run an in-cluster replay of your local recordings (“Run in cluster”) and stream results live

This path is best when you want realistic in-environment behavior or to validate changes inside the cluster. The steps below use the classic cluster-wide operator. For a cluster that cannot grant CRDs, webhooks, or cluster RBAC, use the [namespaced installation guide](https://docs.speedscale.com/getting-started/installation/install/kubernetes-namespaced/) and its [sidecar capture workflow](https://docs.speedscale.com/guides/capture/sidecar-namespaced/). Namespaced mode does not support the eBPF or Java Agent capture steps below. Its local replay has [version-specific limits](https://docs.speedscale.com/getting-started/installation/install/kubernetes-namespaced-limitations/).

Let your coding agent do the whole loop

The [agent tutorial in your cluster](https://docs.speedscale.com/proxymock/agent-tutorial-cluster/) has your coding agent install the operator, record a demo workload with eBPF capture, and replay it in the cluster as a regression test and a load test, one prompt per chapter.

<a id="prerequisites"></a>

## Prerequisites

*   Kubernetes cluster access (`kubectl` working, correct context)
*   Authorized (if you plan to run in-cluster replay): `proxymock init` (browser sign-in)

Let your coding agent do steps 1 and 2

Paste the prompt from [Install with your coding agent](https://docs.speedscale.com/getting-started/quick-start/#install-with-ai-agent) into Claude Code, Cursor, Codex, or any agent that can run commands. It installs proxymock, signs you in, and installs the Speedscale Operator into your cluster, asking before it touches the cluster. Prefer to install manually? Follow steps 1 and 2 below.

<a id="1-install-the-proxymock-cli-if-not-installed"></a>

## 1) Install the proxymock CLI (if not installed)

Install proxymock locally — this gives you both the CLI and `proxymock web`.

**macOS**

Install with [Homebrew](https://brew.sh/):

```shell
brew install speedscale/tap/proxymock
```

**Linux**

Run the install script:

```shell
sh -c "$(curl -Lfs https://downloads.speedscale.com/proxymock/install-proxymock)"
```

**Other / Detailed**

See: [/proxymock/getting-started/installation](https://docs.speedscale.com/proxymock/getting-started/installation/)

After install, initialize once (browser sign-in by default):

```bash
proxymock init
```

<a id="2-install-the-speedscale-operator-if-not-installed"></a>

## 2) Install the Speedscale Operator (if not installed)

If your cluster does not have the Speedscale operator and forwarder yet, follow the [standard operator installation](https://docs.speedscale.com/getting-started/installation/install/kubernetes-operator/). Choose your installation method, enable eBPF, and complete the verification steps before continuing here.

Once installed and reachable, proxymock web will detect the Forwarder and enable Observability and live features via Kubernetes port-forwarding.

Kubernetes Permissions Required

To use **proxymock web** with your cluster, you must have Kubernetes RBAC permissions that allow **port forwarding**.  
If you cannot port-forward (e.g., on restricted clusters), use the **cloud-based replay** feature in Speedscale instead.

<a id="3-start-proxymock-web-and-connect-to-your-cluster"></a>

## 3) Start proxymock web and connect to your cluster

```bash
proxymock web
# Open the printed http://127.0.0.1:XXXX URL
```

*   Open Observability → Topology.
*   If not connected, use the Retry control (proxymock web auto port-forwards to the Forwarder when possible).
*   Optionally switch kube context from the toolbar.

![Observability → Topology with the cluster connected](https://docs.speedscale.com/assets/images/proxymock-web-observability-connect-7814fd09ba8b948c4f245d0673d4b761.png)

![Switch kube context from the toolbar](https://docs.speedscale.com/assets/images/proxymock-web-kube-context-83b759a38d3070e998e0c1519a0e041b.png)

<a id="4-record-traffic-from-a-workload-ebpf-capture"></a>

## 4) Record traffic from a workload (eBPF capture)

From Observability → Topology:

1.  Pick a namespace and select a workload (Deployment/StatefulSet/etc.)
2.  Open the workload pane and enable Capture (eBPF)
3.  Generate traffic (e.g., hit your service from a client)

Requests will stream back and appear in the Requests tab. The persistent live-tap card shows active sessions and counters.

![Selected workload pane with Overview tab](https://docs.speedscale.com/assets/images/proxymock-web-workload-pane-07be9c4c3416d4693c7b9213c117b43b.png)

![eBPF capture toggle on the workload pane](https://docs.speedscale.com/assets/images/proxymock-web-capture-toggle-4484d9ca27ec6eaa88aa8a0630a574db.png)

![Persistent live-tap card with active session and counters](https://docs.speedscale.com/assets/images/proxymock-web-tap-card-f8ef8da9c739f416fe2bd7563f394f5c.png)

Tips:

*   Java services: enable the Java agent checkbox when prompted
*   Ports: set custom capture ports when your service listens on non-default ports

<a id="5-inspect-captured-traffic"></a>

## 5) Inspect captured traffic

Go to Requests → pick the active run from the Run selector. Inspect inbound/outbound RRPairs, filter by host, method, path, and drill into details.

![Requests grid with Run selector](https://docs.speedscale.com/assets/images/proxymock-web-requests-run-0f26d99f9cda8431d0fa714cc3e0fa0f.png)

![Drilled-in RRPair detail pane](https://docs.speedscale.com/assets/images/proxymock-web-request-detail-5d3112e85009b22a9429028214a8e004.png)

<a id="6-optional---run-in-cluster-replay-recordings-inside-your-cluster"></a>

## 6) Optional - Run in cluster (replay recordings inside your cluster)

Any local recordings (`./proxymock/recorded-*`) can be replayed against a workload in your connected cluster.

This path runs entirely through the Kubernetes API. proxymock reaches the cluster with your kubeconfig, analyzes the recordings on this machine, and stages the snapshot directly in the in-cluster forwarder over a port-forward. **The snapshot is never sent to Speedscale cloud**, no cloud login is needed, and the report stays in the cluster. Results stream back live over the Forwarder tap.

Steps (Replay tab):

1.  In **Where it runs**, pick **In your cluster**
2.  Pick one or more recordings
3.  Choose the **Cluster context** and the **Namespace** your workload runs in
4.  Set **Send all to** to a **Workload** or **Service**. A plain URL is resolved inside the generator pod, not on your machine
5.  Every recorded outbound dependency is mocked by default, so the workload answers from the recording instead of reaching the real thing. Open **Options** to mock only some, or none
6.  Click **Run in cluster**

While running:

*   The Live tab shows a stage stepper and streams generator, responder and SUT logs
*   The persistent live-tap card shows 'Live replay' with counters

On completion, proxymock web opens the report and scopes the Requests tab to the run output directory. The report stays in the cluster, so there is no dashboard link; past runs are listed under the **Cluster runs** tab.

![Choosing In your cluster, with the cluster context and namespace pickers](https://docs.speedscale.com/assets/images/replay-where-cluster-c2c2df8b0faba1eee1d6f246c91bb552.png)

Troubleshooting:

*   If **In your cluster** is disabled, proxymock web cannot reach the forwarder. Check that Observability shows a connected cluster and that you started proxymock web with the right `--kube-context`
*   Mocking requires a Workload or Service destination, not a URL
*   To run the same recordings through Speedscale cloud instead, pick **Via Speedscale cloud**. See [Choose Where a Replay Runs](https://docs.speedscale.com/proxymock/guides/replay-paths/)

<a id="next-steps"></a>

## Next steps

*   [Local quickstart](https://docs.speedscale.com/proxymock/getting-started/quickstart/local/) — record and replay traffic against an app on your machine, no cluster required
*   [Live Tail (Web)](https://docs.speedscale.com/proxymock/getting-started/quickstart/live-tail/) — point proxymock web at a running app and watch RRPairs stream in
*   [Observability guide](https://docs.speedscale.com/proxymock/guides/observability/) — go deeper on topology, eBPF capture, and live-tap workflows
*   [How it works](https://docs.speedscale.com/proxymock/how-it-works/architecture/) — architecture, lifecycle, and the RRPair format
*   [Guides index](https://docs.speedscale.com/proxymock/guides/) — credentials swap, CI/CD, OpenAPI, gRPC, databases, and more
