--- title: Remote client configuration --- A remote client is anything outside the Deephaven cluster that connects to it: a browser running the Web UI, a Python or Java program using the Core+ client libraries, a Legacy Swing desktop client, or a headless process such as a [Tailer](./data-tailer.md) or logger running on another machine. Each kind of client discovers Deephaven services, obtains its configuration, and establishes trust in a different way. This page summarizes those differences and points to the pages that cover each mechanism in detail. The [Excel add-in](../../clients/excel-client.md), the [JavaScript API](../../clients/javascript.md), and [MCP](../../clients/mcp.md) have their own connection instructions in the Clients section. ## Client types Each row's label links to the page that covers that client's connection mechanism. The last column names which of the [server-side requirements](#what-the-server-must-expose) the client depends on. | Client | How it connects and gets configuration | What you must provide | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **[Web UI](../core-components/web-api-service.md)** (browser) | Opens a WebSocket to the Web API Service, which proxies the Authentication Service, Controller, and Remote Query Dispatcher on the browser's behalf, and connects directly to Workers (Core+ or Legacy) or to [Envoy](../envoy/envoy.md). Nothing is configured on the client; the Web API Service serves the application and its defaults. | TLS certificate; Web API Service and Worker ports, or Envoy; [CORS settings](./cors.md) if users reach the cluster through a DNS alias. | | **[Core+ programmatic clients](../architecture/connection-json.md)** (Python, Java, C++, R) | Download `connection.json` from the Web API Service once at startup, then connect directly to the Authentication Service, Controller, and Workers. The program supplies its own credentials. The Python client can also be given the JSON document text directly instead of a URL. | TLS certificate or the cluster trust store; `connection.json`; Authentication Service, Controller, and Worker ports, or Envoy. | | **[Legacy Swing clients](../../legacy/legacy-ui/launcher-and-client-configuration.md)** (Deephaven Launcher) | The Launcher downloads `getdown.txt` from the Client Update Service (CUS) and syncs JARs, property files, calendars, and resources each time it starts. Customer settings live in `getdown.global` on the server. Unless Envoy is enabled, the console loads its property files from the Configuration Server through the synced `dh-config/clients` bootstrap directory. It then connects directly to the Authentication Service, Controller, dispatcher, Legacy Workers, and ACL Write Server. | TLS certificate; the CUS; Authentication Service, Configuration Server, Controller, dispatcher, Legacy Worker, and ACL Write Server ports, or Envoy; any extra JARs listed in `customer_jars.txt`. | | **[Headless remote services](./automate-configuration.md)** (Tailers, loggers, custom Java programs that use the Enterprise libraries) | The Deephaven Updater syncs JARs, property files, trust certificates, and a Configuration Server bootstrap directory from the CUS. The process starts with `dh.config.client.bootstrap` pointing at that directory, loads its property files from the [Configuration Server](../core-components/configserver.md), and then authenticates to the services it uses. Re-running the Updater before each start keeps the remote host on the server's version. | TLS certificate or the cluster trust store; the CUS, if you use the Updater (recommended); a credential such as a private key; Authentication Service and Configuration Server ports, plus the ports for whatever service the process talks to, such as the Data Import Server for a [remote Tailer](./data-tailer.md#running-a-remote-tailer-on-linux). | ## What the server must expose Every remote client depends on some combination of the following. Check each one when you set up a new class of client, or when a client that used to work stops connecting after a certificate or network change. - **A trusted TLS certificate.** Clients trust the certificate presented by Envoy when it is enabled, or by the Deephaven service they reach when it is not. A certificate signed by a certificate authority (CA) the client already trusts avoids distributing a trust store. If the cluster uses self-signed certificates, clients need the cluster trust store, which `connection.json` publishes as `truststore_url` and the Updater syncs to remote hosts. See [External TLS trust](../security/tls-certificates.md#external-tls-trust). - **`connection.json`.** The Web API Service serves it at `https://:8123/iris/connection.json` without Envoy, or on port `8000` with Envoy. The Web API Service fills in the Authentication Service and Controller addresses from the cluster's service registry, and the Configuration Server addresses from its own Configuration Server client settings. When Envoy is enabled, all of them are the Envoy address. Those names must match the certificate the client sees. Without Envoy, if you set `ConnectionJson.overrideAuthorities=true`, the document also carries `auth_authority` and `controller_authority`, taken from `authentication.server.overrideAuthority` and `PersistentQueryController.overrideAuthority`, and the client validates those two connections against them instead. The Configuration Server authority is not part of `connection.json`; it comes from the client's [bootstrap directory](./configuration-server-overview.md). See [JSON Connection Configuration Document](../architecture/connection-json.md). - **The Client Update Service.** Required for Legacy Swing clients and for the Deephaven Updater. It runs inside the Web API Service and needs `client_update_service.host` set to the name clients use to reach it. See [Client Update Service](./client-update-service.md). - **Reachable ports, or Envoy.** Without Envoy, clients need the Web API Service, Client Update Service, Authentication Service, Controller, Configuration Server, and Worker ports open between the client network and the cluster. Legacy Swing clients also need the dispatcher and ACL Write Server ports, and remote Tailers need the Data Import Server port. The Client Update Service port also serves the trust store that `connection.json` points Core+ clients to. With Envoy, browsers, Core+ clients, and Swing clients reach everything through a single port. Envoy does not proxy Tailer traffic to the Data Import Server, so that port stays open directly. See [Process ports](../ops-guide/process-ports.md) and [Use Envoy as a front proxy](../envoy/envoy.md). ## Related documentation - [Web API Service](../core-components/web-api-service.md) - [JSON Connection Configuration Document](../architecture/connection-json.md) - [Deephaven Launcher and Client configuration](../../legacy/legacy-ui/launcher-and-client-configuration.md) - [Automate configuration with the Deephaven Updater](./automate-configuration.md) - [Communications protocols](../architecture/communications.md) - [TLS certificates](../security/tls-certificates.md) - [Process ports](../ops-guide/process-ports.md)