Docsright arrowTelepresenceright arrowTelepresence in Docker Mode

9 min • read

Telepresence in Docker Mode


Welcome to the quickstart guide for Telepresence Docker mode! In this hands-on tutorial, we will explore the powerful features of Telepresence and learn how to leverage Telepresence Docker mode to enhance local development and debugging workflows.

What is Telepresence Docker Mode?

Telepresence Docker Mode enables you to run a single service locally while seamlessly connecting it to a remote Kubernetes cluster. This mode enables developers to accelerate their development cycles by providing a fast and efficient way to iterate on code changes without requiring admin access on their machines.

Key Benefits

When using Telepresence in Docker mode, you can enjoy the following benefits:

  1. Simplified Development Setup: Eliminate the need for admin access on your local machine, making it easier to set up and configure your development environment.

  2. Efficient Networking: Address common networking challenges by seamlessly connecting your locally running service to a remote Kubernetes cluster. This enables you to leverage the cluster's resources and dependencies while maintaining a productive local development experience.

  3. Enhanced Debugging: Gain the ability to debug your service in its natural environment, directly from your local development environment. This eliminates the need for complex workarounds or third-party applications to enable volume mounts or access remote resources.


  1. Kubectl. Kubectl is the official Kubernetes command-line tool. You will use it regularly to interact with your cluster, whether deploying applications, inspecting resources, or debugging issues.

  2. Telepresence 2.13 or latest. Telepresence is a command-line tool that lets you run a single service locally, while connecting that service to a remote Kubernetes cluster. You can use Telepresence to speed up local development and debugging.

  3. Docker Desktop. Docker Desktop is a tool for building and sharing containerized applications and microservices. You'll use Docker Desktop to run a local development environment.

Now that we have a clear understanding of Telepresence Docker mode and its benefits, let's dive into the hands-on tutorial!

1. Get a free remote cluster

Telepresence connects your local workstation with a remote Kubernetes cluster. In this tutorial, we'll start with a pre-configured, remote cluster.

  1. Get a Free Remote Cluster
    Sign in to Ambassador Cloud to activate your demo cluster.
  2. Go to the Service Catalog to see all the services deployed on your cluster.The Service Catalog gives you a consolidated view of all your services across development, staging, and production. After exploring the Service Catalog, continue with this tutorial to test the application in your demo cluster.
Wait! The rest of this quick start requires a remote Kubernetes cluster. Before continuing, activate a free demo cluster in step 1 above.

2. Try the Emojivoto application

The remote cluster is running the Emojivoto application, which consists of four services. Test out the application:

  1. Go to the remote demo cluster and vote for some emojis.

  2. Now, click on the 🍩 emoji. You'll see that a bug is present, and voting 🍩 doesn't work. We're going to use Telepresence shortly to fix this bug, as everyone should be able to vote for 🍩!

3. Testing the fix in your local environment

We'll set up a development environment locally on your workstation. We'll then use Telepresence to connect this local development environment to the remote Kubernetes cluster. To save time, the development environment we'll use is pre-packaged as a Docker container.

  1. Download and run the image for the service locally:

    The Docker container includes a copy of the Emojivoto application that fixes the bug. Visit the leaderboard and notice how it is different from the leaderboard in your Kubernetes cluster.

  2. Now, stop the container by running the following command in your terminal:

In this section of the quickstart, you ran the Emojivoto application locally. In the next section, you'll use Telepresence to connect your local development environment to the remote Kubernetes cluster.

4. Download the demo cluster config file

  1. Download your demo cluster config file. This file contains the credentials you need to access your demo cluster.
  2. Export the file's location to KUBECONFIG by running this command in your terminal:


You should now be able to run kubectl commands against your demo cluster.

  1. Verify that you can access the cluster by listing the app's services:

5. Enable Telepresence Docker mode

You can simply add the docker flag to any Telepresence command, and it will start your daemon in a container. Thus removing the need for root access, making it easier to adopt as an organization.

  1. Confirm that the Telepresence CLI is now installed, we expect to see that the daemons are not yet running: telepresence status

  2. Log in to Ambassador Cloud:

  3. Then, install the Helm chart and quit Telepresence:

  4. Finally, connect to the remote cluster using Docker mode:

  5. Verify that you are connected to the remote cluster by listing your Docker containers:

This method limits the scope of the potential networking issues since everything stays inside Docker. The Telepresence daemon can be found under the name tp-<your-context> when listing your containers.

6. Set up your local development environment and make a global intercept

Start your intercept handler (interceptor) by targeting the daemon container --network=container:tp-<your-context>, and open the preview URL to see the traffic routed to your machine.

  1. Run the Docker container locally, by running this command inside your local terminal. The image is the same as the one you ran in the previous step (step 1) but this time, you will run it with the --network=container:tp-<your-context> flag:

  2. With Telepresence, you can create global intercepts that intercept all traffic going to a service in your cluster and route it to your local environment instead/ Start a global intercept by running this command in your terminal:

7. Make a personal intercept

Personal intercepts allow you to be selective and intercept only some of the traffic to a service while not interfering with the rest of the traffic. This allows you to share a cluster with others on your team without interfering with their work.

  1. First, connect to telepresence docker mode again:

  2. Run the docker container again:

  3. Create a personal intercept by running this command in your terminal:

  4. Open the preview URL to see the traffic routed to your machine.

  5. To stop the intercept, run this command in your terminal:

logo What's Next?

You've intercepted a service in one of our demo clusters, now you can use Telepresence to intercept a service in your own environment!