Getting started

outprobe has two halves: a laptop CLI and an in-cluster relay. The CLI creates the relay and routing objects, opens a reverse tunnel through a Kubernetes port-forward, and forwards matched requests to your local app.

Before you begin

You need:

• a Kubernetes cluster using Istio;
• kubectl in your PATH, with a working kubeconfig;
• namespace-level permission to create a Deployment, Service, and the routing resource used by your traffic mode;
• a local HTTP service to receive requests (the default is http://localhost:8080);
• Homebrew to install the CLI.

Gateway API is needed only for optional browser/ingress interception. Docker is needed only when pulling or running a container image.

1. Install outprobe

CLI

brew install outprobe/outprobe
outprobe --help

This is the laptop CLI used for init, up, down, status, and routes.

Relay binary

brew install outprobe/outprobe-relay

Install the relay formula when you need the standalone relay binary.

Relay container

docker pull ghcr.io/flaticols/outprobe-relay:v0.0.16

This is the relay image deployed in the cluster. Pin the same tag in .outprobe.yaml for a reproducible setup:

image: ghcr.io/flaticols/outprobe-relay:v0.0.16

2. Scaffold the config

From the project where you run your local service:

outprobe init

This writes .outprobe.yaml without overwriting an existing file. Its first line points editors at the hosted schema:

# yaml-language-server: $schema=https://outprobe.dev/schemas/outprobe.schema.json

Use outprobe init --manifests only if you also want editable copies of the Kubernetes manifests under .outprobe/.

3. Set the target and your identity

Start with the smallest useful config:

.outprobe.yaml

version: "0.0.1"

namespace: my-namespace
target: my-service
image: ghcr.io/flaticols/outprobe-relay:v0.0.16
localTarget: http://localhost:8080

rules:
  - type: jwt
    property: ""            # top-level claim
    matchers:
      - key: email
        value: you@example.com

The value must equal the value carried by your request. For an email claim, useful lookups are:

Provider	Command	Note
GKE / gcloud	gcloud config get-value account	Usually the email in the token.
fly.io	fly auth whoami	Returns your email.
AWS	aws sts get-caller-identity	Returns an ARN, not necessarily your JWT email.
Any provider	Decode the bearer token at jwt.io	The token claim is the source of truth.

JWTs are decoded, not verified

The relay uses the claim only as a routing hint, never as an authorization decision. Existing gateway/mesh checks still apply where the request traverses them, and your local app must not trust a relay match as proof of identity.

Prefer a header instead? Replace the rule with:

.outprobe.yaml

rules:
  - type: header
    matchers:
      - key: x-debug-user
        value: denis

See Request matching for namespaced claims, feed filters, and current v1 rule selection.

4. Start your local service

Run a local copy of the target service at the configured localTarget. With the default:

http://localhost:8080

Run it under Delve or attach your editor if you want to stop at a breakpoint. outprobe forwards the original method, path, headers, and body to this endpoint.

5. Bring the intercept up

outprobe up

The CLI will:

1. resolve settings using flag/environment → config → built-in defaults;
2. apply and wait for the relay;
3. open an in-process port-forward to the relay’s loopback-only control port;
4. connect 32 tunnel workers and register your rule;
5. apply routing only after workers are connecting;
6. wait until you press Ctrl-C.

When ready, the log ends with a line similar to:

outprobe is live — drive the app; Ctrl-C to tear down  mode=divert target=my-namespace/my-service match="jwt email=you@example.com" local=http://localhost:8080

Drive the shared application. Requests with your matching claim or header should now reach the local service; unmatched requests continue to the real target.

Override deployment settings without editing the file

outprobe up --target other-service, NS=other-namespace outprobe up, and LOCAL_TARGET=http://localhost:3000 outprobe up override only those deployment fields. Request identity always comes from .outprobe.yaml.

Stop and inspect

Press Ctrl-C to tear down. outprobe deletes routing objects first, then the relay, so direct routing is restored before the pod disappears.

If a previous process exited unexpectedly:

outprobe status
outprobe down

Understand the request path

See how outprobe works, including relay dispatch and the reverse tunnel.

Choose a safer mode

Compare divert, mirror, inbound-divert, and inbound-mirror.

Catch browser traffic

Add a narrowly scoped Gateway API route with the ingress guide.

Call cluster dependencies

Expose in-cluster TCP services locally through egress tunnels.