6 min • read

Telepresence Quick Start


In this guide, we'll give you a hands-on tutorial with Telepresence. To go through this tutorial, the only thing you'll need is a computer that runs Docker Desktop. We'll give you a pre-configured remote Kubernetes cluster and a Docker container to run locally.

If you don't have Docker Desktop already installed, go to the Docker download page and install Docker.

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. Sign in to Ambassador Cloud to activate your demo cluster and get its configuration. Note where you've downloaded the kubeconfig.yaml file; you'll need the location of this file later in this guide.
  2. Go to the Service Catalog to see all the services deployed on your cluster:

2. Try the Emojivoto application

The remote cluster is running the Emojivoto application, which consists of three 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. Set up your local development 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. Run the Docker container locally. In the command below, replace the path to the kubeconfig.yaml with the actual location of the kubeconfig.yaml you previously noted in step 1:

    $ docker run -v <PATH_TO_YOUR_DOWNLOADS_FOLDER>/kubeconfig.yaml:/opt/telepresence-demo-cluster.yaml --cap-add=NET_ADMIN --device /dev/net/tun:/dev/net/tun -p8083:8083 -p8080:8080 --pull always --name ambassador-demo --rm -it datawire/demoemojivoto
    Connected to context telepresence-demo (https://$DEMO_CLUSTER_IP)
    emoji : ready to intercept (traffic-agent not yet installed)
    web : ready to intercept (traffic-agent not yet installed)
    voting : ready to intercept (traffic-agent not yet installed)
    web-app-778477c59c: ready to intercept (traffic-agent not yet installed)
  2. 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.

  3. Vote for 🍩 on your local leaderboard, and you can see that the bug is fixed!

4. Testing our fix

A common use case for Telepresence is to connect your local development environment to a remote cluster. This way, if your application is too big or complex to run locally, you can still develop locally. In this Quick Start, we're also going to show Telepresence can be used for integration testing, by testing our fix against the services in the remote cluster.

  1. First, log in to Telepresence using your API key:

    $ telepresence login --apikey $APIKEY
  2. Create an intercept, which will tell Telepresence to send traffic to the service in our container instead of the service in the cluster: telepresence intercept web --port 8080

    You will be asked for your ingress layer 3 address; specify the front end service: ambassador.ambassador Then, when asked for the port, type 80, for "use TLS", type n. The default for the fourth value is correct so hit enter to accept it.

    $ telepresence intercept web --port 8080
    To create a preview URL, telepresence needs to know how cluster
    ingress works for this service. Please Select the ingress to use.
    1/4: What's your ingress' layer 3 (IP) address?
    You may use an IP address or a DNS name (this is usually a
    "service.namespace" DNS name).
    [no default]: ambassador.ambassador
    2/4: What's your ingress' layer 4 address (TCP port number)?
    [no default]: 80
    3/4: Does that TCP port on your ingress use TLS (as opposed to cleartext)?
    [default: n]: n
    4/4: If required by your ingress, specify a different layer 5 hostname
    (TLS-SNI, HTTP "Host" header) to access this service.
    [default: ambassador.ambassador]:

5. Preview URLs

Preview URLs enable you to safely share your development environment with anyone. For example, you may want your UX designer to take a quick look at what you're developing, before you commit the code. Preview URLs enable this easy collaboration.

  1. If you access the Emojivoto application on your remote cluster and vote for the 🍩 emoji, you'll see the bug is still present.

  2. Vote for the 🍩 emoji using the Preview URL obtained in the previous step, and you will see that the bug is fixed, since traffic is being routed to the fixed version running locally.

6. How/Why does this all work

Telepresence works by deploying a two-way network proxy in a pod running in a Kubernetes cluster. This proxy can intercept traffic meant for the service and reroute it to a local copy, which is ready for further (local) development.

Intercepts and preview URLs are functions of Telepresence that enable easy local development from a remote Kubernetes cluster and offer a preview environment for sharing and real-time collaboration.

Telepresence also uses custom headers and header propagation for controllable intercepts and preview URLs. The headers facilitate the smart routing of requests either to live services in the cluster or services running locally on a developer’s machine.

Preview URLs, when created, generate an ingress request containing a custom header with a token (the context). Telepresence sends this token to Ambassador Cloud with other information about the preview. Visiting the preview URL directs the user to Ambassador Cloud, which proxies the user to the cluster ingress with the token header injected into the request. The request carrying the header is routed in the cluster to the appropriate pod (the propagation). The Traffic Agent on the service pod sees the header and intercepts the request, redirecting it to the local developer machine that ran the intercept.

What's Next?


Use preview URLS to collaborate with your colleagues and others outside of your organization.

Outbound Sessions

While connected to the cluster, your laptop can interact with services as if it was another pod in the cluster.


Learn more about uses cases and the technical implementation of Telepresence.


We’re here to help if you have questions.