Skip to main content
This guide explains how to create and manage Telepresence intercepts to route traffic from a Kubernetes service to a process running on your local machine. Intercepts let you develop and debug services locally while other components remain deployed in the cluster. Prerequisites:
  • Telepresence Traffic Manager installed in the cluster.
  • A running telepresence connect session from your laptop or local machine to the cluster.
You must run telepresence connect before creating any intercepts. Without an active connection, intercept commands will fail.

​
How intercepts work (high level)

When you create an intercept for a deployment, Telepresence injects a traffic-agent (sidecar) into the target pod. That sidecar instructs the cluster to route requests destined for the service’s port to your local machine. Service discovery and other cluster services continue to operate normally; Telepresence proxies the traffic from the cluster to the local process you specify. Key concepts:
  • traffic-agent (sidecar): a small proxy injected into the intercepted pod to reroute service traffic.
  • Destination: the local address (e.g., 127.0.0.1:8000) where cluster requests are forwarded.
  • Intercept scope: you can intercept per Deployment/Workload and per service port.

​
Create an intercept

The basic syntax maps a remote service port to a local port:
Example: intercept the products-depl deployment (service port 3000) and forward it to port 8000 on your laptop:
Tips:
  • If the service exposes only a single port, Telepresence can often infer the service port; specifying it is optional.
  • Format is --port <local>:<service>. You may reuse the same number for both sides, e.g. 3000:3000.
  • Intercepts create a traffic-agent sidecar in the intercepted pod to apply routing; the workload remains otherwise unchanged.
Common intercept commands:

​
Example intercept output

When an intercept is successfully established, Telepresence prints details like the example below:
Important fields:

​
List active intercepts

To view current intercepts and their status:
This shows active intercepts, their destination addresses, and the current state.

​
Multiple intercepts and performance considerations

You can create multiple intercepts simultaneously. Example:
Considerations when using multiple intercepts:
  • Local port collisions: pick unique local ports — two processes cannot listen on the same port.
  • Extra cluster hops: when an intercepted service calls another intercepted service, traffic may traverse the cluster twice:
    1. Request enters cluster and is routed to products (intercepted to your laptop).
    2. Your local products calls inventory using cluster DNS.
    3. The call goes into the cluster and then is proxied back to your local inventory intercept.
  • Latency: these extra hops can add latency. Telepresence does not automatically rewrite service discovery to force direct local-to-local calls; any DNS/hosts rewrites or local stubs must be managed by you.
If you need multiple services to talk directly on your machine during development, you’ll typically need to adjust local host resolution or run a local stub that emulates the needed services. Telepresence will not automatically make intercepted services talk directly to other local processes.

​
Collaboration and isolation

Intercepted traffic can be affected by other developers if they target the same service in the same namespace. To avoid confusion or accidental cross-traffic, use per-developer namespaces or personal deployments. Benefits of using separate namespaces:
  • Isolation of intercepts: your intercepts only affect workloads in your namespace.
  • Reduced accidental interference between developers.
  • Easier cleanup and targeted testing.
A diagram titled "Intercept Challenges" showing a laptop tunneling into a Kubernetes cluster with two namespaces (test1 and test2). Each namespace contains services like "products" and "inventory" and a traffic agent, while an "Another User" icon points to the cluster.
By scoping work to namespaces, each developer can intercept services in their own namespace without affecting others.

​
Summary

  • Start with telepresence connect.
  • Create an intercept with telepresence intercept <deployment> --port <local_port>:<service_port> to forward cluster traffic to a local process.
  • Inspect active intercepts with telepresence list.
  • Multiple intercepts are supported but can introduce extra cluster hops and latency.
  • Use per-developer namespaces to reduce cross-traffic and accidental interference.

Watch Video