Clients

The on-prem agent: install, register, monitor.

A client is the on-prem agent that does the actual reading from your sources — and, when it owns a client-placed sink connection, the actual writing to your destinations. It is a native Windows Service, distributed as an MSI installer, and it initiates every connection to the server. The Clients page is where you register clients, watch their status, and manage their keys.

What a client is

• A native Windows Service — not a container. Docker is not required (and not supported) on the on-prem machine.
• Installed from an MSI installer. A small tray icon opens the client's local configuration UI on localhost.
• It pulls all of its work from the server. It never accepts inbound connections.

The client keeps itself up to date by pulling a new binary from the server when an update is published; the update still happens on the client's own poll, never by a server push.

Reading and writing

A client is not only a reader. What it does on a run follows the placement of the connections a transport uses (see Connections):

• It reads a source when the source connection is placed on it — the classic on-prem case — and ships the rows to the server.
• It writes a destination when the sink connection is placed on it. The write runs in-process on the client: it either reads a local source and writes locally (one client owns both sides, so the data never leaves the machine), or pulls the rows from the server over Flight and writes them out. Every sink family a client can own is written this way — object-store files (Parquet, CSV), self-contained warehouses (Databricks, Fabric), and table formats (Iceberg, S3 Tables) — producing the same result a server-side write would.

Placing a sink on a client keeps the destination reachable only from inside your network; the server never needs a route to it.

Registering a client

On the Clients page, create a new client with a name and an optional description, then pick a delivery method for its credentials:

• Show connection string — the server returns a connection string (an endpoint plus a key). You copy it and paste it into the client's tray configuration on the target machine. Use this when you have desktop access to the machine.
• Generate install command — the server returns a one-line PowerShell command containing a short-lived, single-use bootstrap token (valid for one hour). An admin runs it on the on-prem machine; the install script exchanges the token for the connection string and writes the client configuration in one step. Use this for headless machines where you only have a remote shell.

The credential is shown only once. Copy it immediately. For the install command, the token expires after one hour and works only once — anyone who runs it registers this client, so do not share it publicly.

Online / offline status

Once a client has applied its connection string (or completed the install command), it begins polling and shows as online in the list. A client that stops polling — because the machine is off, the service is stopped, or it lost network — shows as offline. Because everything is client-initiated, an offline client causes no errors on the server; its transports simply do not run until it comes back.

Rotating a client's key

The connection-string key can be rotated. Two flavours are available from the row's action menu:

• Rotate key (soft rotate) — the server queues a new key; the client picks it up on its next poll and switches over automatically. The new key never reaches your clipboard, and no manual re-delivery is needed. Use this for routine, scheduled rotation.
• Re-issue connection string (hard rotate) — the current key is invalidated immediately and a fresh connection string (or install command) is issued for re-delivery. Use this when the original credential was lost or leaked. The on-prem client must receive the new credential to keep working.

In addition, the server can rotate keys automatically on a configurable cadence. During a soft rotation the old key stays valid until the client acknowledges the new one on its first poll under it, so there is no window where the client is locked out.

Roles and visibility

Read-only users (the Viewer role) can see clients and their status but cannot register clients, rotate keys, or re-issue credentials. Those actions require Operator or Admin. See Authentication & Roles.

Distributing the installer

The MSI installer and its release notes are published from the server. Administrators manage which version is the current download on the Settings → Client distribution page. See Runtime Settings & Administration.

Checking clients from your phone

The Mobile app has a Clients tab listing every client offline-first, expandable to its last-seen time and host vitals. It is the quickest way to answer "is a client down?" — worth knowing, because a run assigned to an offline client simply waits in Queued and raises no error until it times out.