Docsright arrowTelepresenceright arrowLaptop-side configuration

14 min • read

Laptop-side configuration

There are a number of configuration values that can be tweaked to change how Telepresence behaves. These can be set in two ways: globally, by a platform engineer with powers to deploy the Telepresence Traffic Manager, or locally by any user. One important exception is the location of the traffic manager itself, which, if it's different from the default of ambassador, must be set locally per-cluster to be able to connect.

Global Configuration

Global configuration is set at the Traffic Manager level and applies to any user connecting to that Traffic Manager. To set it, simply pass in a client dictionary to the telepresence helm install command, with any config values you wish to set.

The client config supports values for cloud, cluster, dns, grpc, images, logLevels, routing, systray, telepresenceAPI, and timeouts.

Here is an example configuration to show you the conventions of how Telepresence is configured: note: This config shouldn't be used verbatim, since the registry privateRepo used doesn't exist


Values for are listed below and their type varies, so please see the chart for the expected type for each config value. These fields control how the client interacts with the Cloud service.

skipLoginPrint an error instead of prompting the user to login, in case a login is necessary.booleanfalse
systemaHostThe host used to communicate with Ambassador
systemaPortThe port used with systemaHost to communicate with Ambassador Cloudstring443


Values for client.cluster controls aspects on how client's connection to the traffic-manager.

defaultManagerNamespaceThe default namespace where the Traffic Manager will be installed.stringambassador
mappedNamespacesNamespaces that will be mapped by default.sequence of strings[]
connectFromRootDaeamonMake connections to the cluster directly from the root daemon.booleantrue
agentPortForwardLet telepresence-client use port-forwards directly to agentsbooleantrue
virtualIPSubnetThe CIDR to use when generating virtual IPsstringplatform dependent


The client.dns configuration offers options for configuring the DNS resolution behavior in a client application or system. Here is a summary of the available fields:

The fields for client.dns are: localIP, excludeSuffixes, includeSuffixes, and lookupTimeout.

localIPThe address of the local DNS server. This entry is only used on Linux systems that are not configured to use systemd-resolved.IP address stringfirst nameserver mentioned in /etc/resolv.conf
excludeSuffixesSuffixes for which the DNS resolver will always fail (or fallback in case of the overriding resolver). Can be globally configured in the Helm chart.sequence of strings[".arpa", ".com", ".io", ".net", ".org", ".ru"]
includeSuffixesSuffixes for which the DNS resolver will always attempt to do a lookup. Includes have higher priority than excludes. Can be globally configured in the Helm chart.sequence of strings[]
excludesNames to be excluded by the DNS resolver[]
mappingsNames to be resolved to other names (CNAME records) or to explicit IP addresses[]
lookupTimeoutMaximum time to wait for a cluster side host lookup.duration string4 seconds

Here is an example values.yaml:


Allows you to map hostnames to aliases or to IP addresses. This is useful when you want to use an alternative name for a service in the cluster, or when you want the DNS resolver to map a name to an IP address of your choice.

In the given cluster, the service named postgres is located within a separate namespace titled big-data, and it's referred to as psql :


Lists service names to be excluded from the Telepresence DNS server. This is useful when you want your application to interact with a local service instead of a cluster service. In this example, "redis" will not be resolved by the cluster, but locally.


The maxReceiveSize determines how large a message that the workstation receives via gRPC can be. The default is 4Mi (determined by gRPC). All traffic to and from the cluster is tunneled via gRPC.

The size is measured in bytes. You can express it as a plain integer or as a fixed-point number using E, G, M, or K. You can also use the power-of-two equivalents: Gi, Mi, Ki. For example, the following represent roughly the same value:


Values for client.images are strings. These values affect the objects that are deployed in the cluster, so it's important to ensure users have the same configuration.

These are the valid fields for the client.images key:

registryDocker registry to be used for installing the Traffic Manager and default Traffic Agent.Docker registry name
agentImage$registry/$imageName:$imageTag to use when installing the Traffic Agent.qualified Docker image name string(unset)
clientImage$registry/$imageName:$imageTag to use locally when connecting with --docker.qualified Docker image name string$registry/ambassador-telepresence


The intercept controls applies to how Telepresence will intercept the communications to the intercepted service.

appProtocolStrategyControls how Telepresence selects the application protocol to use when intercepting a service that has no service.ports.appProtocol defined.appProtocolStrategyhttp2Probe
defaultPortcontrols which port is selected when no --port flag is given to the telepresence intercept command.int8080
useFtpUse fuseftp instead of sshfs when mounting remote file systemsbooleanfalse

The appProtocolStrategy is only relevant when using personal intercepts. Valid values are:

ValueResulting action
http2ProbeThe Telepresence Traffic Agent will probe the intercepted container to check whether it supports http2
portNameTelepresence will make an educated guess about the protocol based on the name of the service port
httpTelepresence will use http
http2Telepresence will use http2

When portName is used, Telepresence will determine the protocol by the name of the port: <protocol>[-suffix]. The following protocols are recognized:

httpPlaintext HTTP/1.1 traffic
http2Plaintext HTTP/2 traffic
httpsTLS Encrypted HTTP (1.1 or 2) traffic
grpcSame as http2

Log Levels

Values for the client.logLevels fields are one of the following strings, case-insensitive:

  • trace
  • debug
  • info
  • warning or warn
  • error

For whichever log-level you select, you will get logs labeled with that level and of higher severity. (e.g. if you use info, you will also get logs labeled error. You will NOT get logs labeled debug.

These are the valid fields for the client.logLevels key:

userDaemonLogging level to be used by the User Daemon (logs to connector.log)loglevel stringdebug
rootDaemonLogging level to be used for the Root Daemon (logs to daemon.log)loglevel stringinfo



When using alsoProxySubnets, you provide a list of subnets to be added to the TUN device. All connections to addresses that the subnet spans will be dispatched to the cluster

Here is an example values.yaml for the subnet


When using neverProxySubnets you provide a list of subnets. These will never be routed via the TUN device, even if they fall within the subnets (pod or service) for the cluster. Instead, whatever route they have before telepresence connects is the route they will keep.

Here is an example kubeconfig for the subnet

Using AlsoProxy together with NeverProxy

Never proxy and also proxy are implemented as routing rules, meaning that when the two conflict, regular routing routes apply. Usually this means that the most specific route will win.

So, for example, if an alsoProxySubnets subnet falls within a broader neverProxySubnets subnet:

Then the specific alsoProxySubnets of will be proxied by the TUN device, whereas the rest of will not.

Conversely, if a neverProxySubnets subnet is inside a larger alsoProxySubnets subnet:

Then all of the alsoProxySubnets of will be proxied, with the exception of the specific neverProxySubnets of


Values for client.systray can be used to configure the systray application.

enabledEnable/disable the systray application.booleantrue
includeContextsKubernetes contexts to include in the menu.sequence of strings[] (all)
excludeContextsKubernetes contexts to exclude from the menu.sequence of strings[] (none)


The client.telepresenceAPI controls the behavior of Telepresence's RESTful API server that can be queried for additional information about ongoing intercepts. When present, and the port is set to a valid port number, it's propagated to the auto-installer so that application containers that can be intercepted gets the TELEPRESENCE_API_PORT environment set. The server can then be queried at localhost:<TELEPRESENCE_API_PORT>. In addition, the traffic-agent and the user-daemon on the workstation that performs an intercept will start the server on that port. If the traffic-manager is auto-installed, its webhook agent injector will be configured to add the TELEPRESENCE_API_PORT environment to the app container when the traffic-agent is injected. See RESTful API server for more info.


Values for client.timeouts are all durations either as a number of seconds or as a string with a unit suffix of ms, s, m, or h. Strings can be fractional (1.5h) or combined (2h45m).

These are the valid fields for the timeouts key:

agentInstallWaiting for Traffic Agent to be installedint or float number of seconds, or duration string2 minutes
applyWaiting for a Kubernetes manifest to be appliedint or float number of seconds, or duration string1 minute
clusterConnectWaiting for cluster to be connectedint or float number of seconds, or duration string20 seconds
connectivityCheckTimeout used when checking if cluster is already proxied on the workstationint or float number of seconds, or duration string500 ms
endpointDialWaiting for a Dial to a service for which the IP is knownint or float number of seconds, or duration string3 seconds
roundtripLatencyHow much to add to the endpointDial timeout when establishing a remote connectionint or float number of seconds, or duration string2 seconds
interceptWaiting for an intercept to become activeint or float number of seconds, or duration string30 seconds
proxyDialWaiting for an outbound connection to be establishedint or float number of seconds, or duration string5 seconds
trafficManagerConnectWaiting for the Traffic Manager API to connect for port forwardsint or float number of seconds, or duration string60 seconds
trafficManagerAPIWaiting for connection to the gPRC API after trafficManagerConnect is successfulint or float number of seconds, or duration string15 seconds
helmWaiting for Helm operations (e.g. install) on the Traffic Managerint or float number of seconds, or duration string30 seconds

Local Overrides

In addition, it is possible to override each of these variables at the local level by setting up new values in local config files. There are two types of config values that can be set locally: those that apply to all clusters, which are set in a single config.yml file, and those that only apply to specific clusters, which are set as extensions to the $KUBECONFIG file.

Config for all clusters

Telepresence uses a config.yml file to store and change those configuration values that will be used for all clusters you use Telepresence with. The location of this file varies based on your OS:

  • macOS: $HOME/Library/Application Support/telepresence/config.yml
  • Linux: $XDG_CONFIG_HOME/telepresence/config.yml or, if that variable is not set, $HOME/.config/telepresence/config.yml
  • Windows: %APPDATA%\telepresence\config.yml

For Linux, the above paths are for a user-level configuration. For system-level configuration, use the file at $XDG_CONFIG_DIRS/telepresence/config.yml or, if that variable is empty, /etc/xdg/telepresence/config.yml. If a file exists at both the user-level and system-level paths, the user-level path file will take precedence.


The config file currently supports values for the cloud, cluster, grpc, images, logLevels, systray, telepresenceAPI, and timeouts keys. The definitions of these values are identical to those values in the client config above.

Here is an example configuration to show you the conventions of how Telepresence is configured: note: This config shouldn't be used verbatim, since the registry privateRepo used doesn't exist

Workstation Per-Cluster Configuration

Configuration that is specific to a cluster can also be overriden per-workstation by modifying your $KUBECONFIG file. It is recommended that you do not do this, and instead rely on upstream values provided to the Traffic Manager. This ensures that all users that connect to the Traffic Manager will have the same routing and DNS resolution behavior. An important exception to this is the manager.namespace configuration which must be set locally.


The kubeconfig supports values for dns, also-proxy, never-proxy, and manager.

Example kubeconfig:


This is the one cluster configuration that cannot be set using the Helm chart because it defines how Telepresence connects to the Traffic manager. When not default, that setting needs to be configured in the workstation's kubeconfig for the cluster.

The manager key contains configuration for finding the traffic-manager that telepresence will connect to. It supports one key, namespace, indicating the namespace where the traffic manager is to be found

Here is an example kubeconfig that will instruct telepresence to connect to a manager in namespace staging: