Skip to main content

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.

Prerequisites​

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

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

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

Install with Homebrew:

brew install speedscale/tap/proxymock

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

proxymock init

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

If your cluster doesn’t have the Speedscale Operator and Forwarder yet, install them first. Full instructions live here: /getting-started/installation/install/kubernetes-operator/

Quick Helm example:

helm repo add speedscale https://speedscale.github.io/operator-helm/
helm repo update
helm install speedscale-operator speedscale/speedscale-operator \
  -n speedscale \
  --create-namespace \
  --set apiKey=<YOUR-SPEEDSCALE-API-KEY> \
  --set clusterName=<YOUR-CLUSTER-NAME>

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.

3) Start proxymock web and connect to your cluster​

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

Switch kube context from the toolbar

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

eBPF capture toggle on the workload pane

Persistent live-tap card with active session and counters

Tips:

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

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

Drilled-in RRPair detail pane

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. Optional: open Options to mock outbound dependencies, so the workload answers from the recording instead of reaching the real thing
  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

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

Next steps​

  • Local quickstart — record and replay traffic against an app on your machine, no cluster required
  • Live Tail (Web) — point proxymock web at a running app and watch RRPairs stream in
  • Observability guide — go deeper on topology, eBPF capture, and live-tap workflows
  • How it works — architecture, lifecycle, and the RRPair format
  • Guides index — credentials swap, CI/CD, OpenAPI, gRPC, databases, and more