Demo Telepresence with Docker

In this lesson we’ll demonstrate running the Telepresence user daemon inside a Docker container on your local machine. Running Telepresence in Docker is less intrusive than changing host networking, avoids requiring elevated privileges, and makes it easier to run Telepresence alongside other local tooling.

A presentation slide with "Demo" on the left and a turquoise curved panel on the right reading "Telepresence with Docker." The slide also shows a small "© Copyright KodeKloud" note in the bottom-left corner.

Prerequisites:

Telepresence installed (v2.x+ recommended)
Docker installed and running
Access to a Kubernetes cluster (context configured)

1) Run the Telepresence user daemon inside Docker

First, disconnect any active Telepresence session and then connect using the --docker flag to run the Telepresence user daemon inside a container:

# Stop any existing Telepresence session
telepresence quit

# Start Telepresence user daemon in Docker
telepresence connect --docker

You should see console output similar to:

› telepresence quit
Disconnected

› telepresence connect --docker
Launching Telepresence User Daemon
Connected to context arn:aws:eks:us-east-1:195275640053:cluster/telepresence, namespace default (https://C22C5458C5800FD626C361045762447E.gr7.us-east-1.eks.amazonaws.com)

Verify the Telepresence status and confirm the daemon runs in a container:

telepresence status

Example (abridged) status output:

OSS Daemon in container arn_aws_eks_us-east-1_195275640053_cluster_telepresence-default-cn: Running
Version                : 2.20.0
Status                 : Connected
Kubernetes context     : arn:aws:eks:us-east-1:195275640053:cluster/telepresence
Container network      : container:tp-arn_aws_eks_us-east-1_195275640053_cluster_telepresence-default-cn
Namespace              : default
Intercepts             : 0 total
DNS Local IP           : 127.0.0.11
DNS Remote IP          : 192.168.45.89

And confirm with Docker:

docker ps

Example:

CONTAINER ID   IMAGE                                         COMMAND                  CREATED         STATUS         PORTS
469b3ff7dcdb   ghcr.io/telepresenceio/telepresence:2.20.0   "telepresence connec..." 18 seconds ago  Up 17 seconds   127.0.1:42715->42715/tcp  tp-arn_aws_eks_us-east-1_195275640053_cluster_telepresence-default-cn

Running Telepresence inside Docker avoids changing host networking and needing admin privileges while still enabling Kubernetes service interception and local debugging workflows.

2) Intercept cluster traffic to a local Docker container

The common workflow is to intercept traffic destined for a Kubernetes Service/Deployment and forward it to a process running locally. With Telepresence you can run that process inside a Docker container. Example Node.js “auth” service (index.js):

// index.js (auth service)
const express = require("express");
const app = express();
const port = 8000;

app.get("/", (req, res) => {
  res.json({ message: "this is the auth service running on my machine" });
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Build an image and create an intercept that runs your image locally with --docker-run:

# Build image from current directory
docker build -t telepresence-auth:v2 .

# Create a Telepresence intercept that runs the image in a container.
# `--docker-run` tells Telepresence to run your code inside Docker.
# The `--` separates Telepresence flags from Docker flags/args.
telepresence intercept auth-depl --port 8000 --docker-run -- telepresence-auth:v2

When you run an intercept with --docker-run, Telepresence starts the specified image locally and attaches the intercept so cluster traffic to the intercepted service is routed to that container. Confirm the container is running:

docker ps

The double dash (--) separates flags intended for Telepresence from flags and arguments passed to Docker (for example -v, -e, or the container’s CMD). Everything after -- is treated as Docker arguments.

3) Example: Product service — modify code, build, and intercept

Make code changes to the products service and run it locally via Telepresence. The snippet below shows an async route that fetches inventory data, merges it into product objects, and returns the combined result. Replace the inventory fetch URL with the appropriate service address in your setup (for example http://inventory-service:3000).

// snippet from products service
app.get("/", async (req, res) => {
  try {
    // fetch inventory data from the inventory service
    const response = await fetch("http://inventory-service:3000/inventory");
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    const { data } = await response.json();

    const productsWithInventory = filteredProducts.map((product) => {
      return {
        ...product,
        inventoryCount: data[product.id] || 0,
      };
    });

    res.json({ data: productsWithInventory, message: "running on container on local machine" });
  } catch (e) {
    console.error(e);
    res.status(500).json({ error: e.message });
  }
});

Build the Docker image:

docker build -t my-test-image .

Intercept the products-depl deployment and run your image locally:

telepresence intercept products-depl --port 8000 --docker-run -- my-test-image

Sample Telepresence intercept output (abridged):

Using Deployment products-depl
  Intercept name         : products-depl
  State                  : ACTIVE
  Workload kind          : Deployment
  Destination            : 127.0.0.1:8000
  Service Port Identifier: 3000/TCP
  Intercepting           : all TCP connections

Example app listening on port 8000

Test via the product service external endpoint (replace the example ELB host with your own):

curl a2517fc7ab3ee41999dd7c47eed9f866-376507947.us-east-1.elb.amazonaws.com:3000/?product_ids=1,2,3

Example JSON response:

{
  "data": [
    { "id": 1, "name": "iphone 14", "price": 900, "category": "electronics", "onSale": false, "inventoryCount": 864 },
    { "id": 2, "name": "Samsung 40in TV", "price": 500, "category": "electronics", "onSale": true, "inventoryCount": 911 },
    { "id": 3, "name": "Apple MacbookPro", "price": 2500, "category": "electronics", "onSale": false, "inventoryCount": 189 }
  ],
  "message": "running on container on local machine"
}

4) Avoid rebuilding images on every change — use bind mounts and hot-reload

Rebuilding images for every code change slows down iteration. Use Docker bind mounts to map your local source directory into the container and override the container command to a development runner (for example npm run dev using nodemon) so the container picks up file changes instantly. Example: bind-mount the current directory into /usr/src/app in the container and run npm run dev:

telepresence intercept products-depl --port 8000 --docker-run -- -v $(pwd):/usr/src/app my-test-image npm run dev

Notes:

-v $(pwd):/usr/src/app mounts your local project into the container path expected by your Dockerfile.
my-test-image is the base image used to start the container.
npm run dev (after the image name) becomes the container’s command so nodemon will hot-reload on file changes.

Example nodemon container logs:

> products@1.0.0 dev
> nodemon index.js

[nodemon] 3.1.7
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,cjs,json
[nodemon] starting `node index.js`
http://inventory-service:3000/
Example app listening on port 8000

When you update local files, nodemon restarts the server inside the container immediately because the source is bind-mounted.

5) Let Telepresence build the image for you with —docker-build

If you prefer Telepresence to build the image automatically, use --docker-build and --docker-build-opt to pass build options like tag=. Telepresence expects a literal IMAGE token at the end (after the final --) which it replaces with the built image. Example:

telepresence intercept products-depl \
  --port 8000 \
  --docker-build products/ \
  --docker-build-opt tag=my-debug-image \
  -- IMAGE

Notes:

products/ is the path with your Dockerfile.
--docker-build-opt tag=my-debug-image tags the generated image as my-debug-image.
The literal IMAGE token is required; Telepresence uses it to hook the built image into the intercept.

Verify the container and the built image:

docker ps
docker image ls | grep my-debug-image

Example snippets:

docker ps
CONTAINER ID   IMAGE                      NAMES                               COMMAND                  CREATED         STATUS         PORTS
2c1f9448a12f   75d1f2ff141f               intercept-products-depl-8000        "docker-entrypoint.s..."  8 seconds ago   Up 8 seconds

docker image ls
my-debug-image   latest   75d1f2ff141f   3 minutes ago   ...

You can still use bind mounts (-v) and override commands with --docker-build to enable hot-reload workflows.

Quick reference: common Telepresence + Docker commands

Command	Purpose	Example
Connect Telepresence inside Docker	Run user daemon inside a container	`telepresence connect --docker`
Show Telepresence status	Verify daemon & intercepts	`telepresence status`
Run local image as intercept target	Run your image locally and attach intercept	`telepresence intercept auth-depl --port 8000 --docker-run -- telepresence-auth:v2`
Use bind mount & hot-reload	Mount source and run dev command in container	`telepresence intercept products-depl --port 8000 --docker-run -- -v $(pwd):/usr/src/app my-test-image npm run dev`
Let Telepresence build image	Build image from source and run it	`telepresence intercept products-depl --port 8000 --docker-build products/ --docker-build-opt tag=my-debug-image -- IMAGE`

Summary

Use telepresence connect --docker to run the Telepresence user daemon inside a Docker container.
Use telepresence intercept ... --docker-run -- <image> [docker-args] [cmd] to run a local container as the intercept target.
Use Docker bind mounts (-v) and override the container command (e.g., npm run dev) to enable hot-reload without rebuilding images.
Use --docker-build and --docker-build-opt to have Telepresence build the image for you.
The -- separator is critical: flags before it apply to Telepresence; everything after it is passed to Docker.

Links and further reading:

Course Introduction

Telepresence For Kubernetes

Demo Telepresence with Docker

1) Run the Telepresence user daemon inside Docker

2) Intercept cluster traffic to a local Docker container

3) Example: Product service — modify code, build, and intercept

4) Avoid rebuilding images on every change — use bind mounts and hot-reload

5) Let Telepresence build the image for you with —docker-build

Quick reference: common Telepresence + Docker commands

Summary

Watch Video

​1) Run the Telepresence user daemon inside Docker

​2) Intercept cluster traffic to a local Docker container

​3) Example: Product service — modify code, build, and intercept

​4) Avoid rebuilding images on every change — use bind mounts and hot-reload

​5) Let Telepresence build the image for you with —docker-build

​Quick reference: common Telepresence + Docker commands

​Summary

Watch Video

1) Run the Telepresence user daemon inside Docker

2) Intercept cluster traffic to a local Docker container

3) Example: Product service — modify code, build, and intercept

4) Avoid rebuilding images on every change — use bind mounts and hot-reload

5) Let Telepresence build the image for you with —docker-build

Quick reference: common Telepresence + Docker commands

Summary