Skip to main content
In this guide, you’ll learn how to run the Telepresence daemon inside a Docker container. This method avoids modifications to the host’s network configuration and does not require admin privileges.

​
Table of Contents

​
1. Run Telepresence in Docker

First, ensure any existing Telepresence session is terminated, then start a new session with the daemon running inside a Docker container. 
telepresence quit
telepresence connect --docker
# Launching Telepresence User Daemon
# Connected to context arn:aws:eks:us-east-1:195725640053:cluster/telepresence, namespace default (...)
Make sure your Kubernetes context and namespace are correctly configured before running telepresence connect --docker.

​
Verify Telepresence Status

telepresence status
# OSS Daemon in container arn:aws:eks:us-east-1:195725640053:cluster_telepresence-default-cn: Running
# Version            : 2.20.0
# Status             : Connected
# Kubernetes context : arn:aws:eks:us-east-1:195725640053:cluster/telepresence
# ... (additional info) ...

​
Confirm the Daemon Container

docker ps
# CONTAINER ID   IMAGE                                        COMMAND                  CREATED         STATUS         PORTS
# 469b3f77cdcb   ghcr.io/telepresenceio/telepresence:2.20.0   "telepresence connec…"   18 seconds ago  Up 17 seconds  127.0.0.1:42715->42715/tcp   tp-arn_aws_eks_us-east-1_195725640053_cluster_telepresence-default-cn

​
2. Intercepting the Auth Service

​
2.1 Inspect Cluster Services

kubectl get svc
# NAME               TYPE           CLUSTER-IP      PORT(S)          AGE
# auth-service       ClusterIP      10.100.10.52    3000/TCP         4h57m
# inventory-service  ClusterIP      10.100.246.69   3000/TCP         5h34m
curl http://auth-service:3000
# {"message":"this is the auth service"}

​
2.2 Update Local Auth Service

In your auth/index.js: 
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}`);
});

​
2.3 Build the Auth Docker Image

cd auth
docker build -t telepresence-auth:v2 .
# ... build output ...

​
2.4 Create the Telepresence Intercept

telepresence intercept auth-depl \
  --port 8000 \
  --docker-run telepresence-auth:v2
# Using Deployment auth-depl
# Intercept name: auth-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

​
2.5 Verify the Auth Container

docker ps
# CONTAINER ID   IMAGE                     NAMES   COMMAND   STATUS
# ...            telepresence-auth:v2      ...     ...       Up ...

​
3. Intercepting the Products Service

​
3.1 Modify the Products Endpoint

Edit products/index.js to confirm local behavior: 
app.get("/", async (req, res) => {
  // ... fetch data ...
  res.json({ data: productsWithInventory, message: "running on container on local machine" });
});

​
3.2 Build and Intercept

cd products
docker build -t my-test-image .
telepresence intercept products-depl \
  --port 8000 \
  --docker-run -- my-test-image
# Using Deployment products-depl
# Intercept name: products-depl
# ...
# Example app listening on port 8000

​
3.3 Test the Products Intercept

kubectl get svc products-service
curl http://a2517fc7ee41999dd7c47eed9f866-376507947.us-east-1.elb.amazonaws.com:3000/?product_ids=1,2,3
# {"data":[...],"message":"running on container on local machine"}

​
4. Hot-Reload with Bind Mounts

Rebuilding images after each change can slow development. Instead, use a bind mount with Nodemon for hot-reload.

​
4.1 Dockerfile for Hot-Reload

FROM node:22
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY .

​
4.2 Update package.json

{
  "scripts": {
    "dev": "nodemon index.js"
  },
  "dependencies": {
    "dotenv": "^16.4.5"
  }
}

​
4.3 Run with Bind Mount and Nodemon

telepresence intercept products-depl \
  --port 8000 \
  --docker-run -- \
    -v $(pwd):/usr/src/app my-test-image npm run dev
# [nodemon] 3.1.7
# [nodemon] to restart at any time, enter `rs`
# [nodemon] starting `node index.js`
# Example app listening on port 8000
Any change in the products directory now triggers an auto-reload inside the container.

​
5. Automatic Image Build with --docker-build

Skip manual builds by letting Telepresence build your image during intercept: 
telepresence intercept products-depl \
  --port 8000 \
  --docker-build products \
  --docker-build-opt tag=my-debug-image \
  -- my-debug-image
# Using Deployment products-depl
# Intercept name: products-depl
# State: ACTIVE
# ...
# Example app listening on port 8000
This command:
  • Builds the image from the products/ directory
  • Tags it as my-debug-image
  • Starts the intercept in one step

​
6. References

Watch Video