Skip to main content
Timbal Connect is Timbal’s on-premises data gateway: a service you install on a server inside your network that acts as a bridge between your databases and file shares and Timbal. It opens one outbound, encrypted connection to Timbal and waits for instructions: browse a schema, run a read-only query, sync a table into a knowledge base, or copy files. You never open an inbound port, and database credentials never leave the server. Timbal only knows each connection by the name you give it; the connection string lives in a file on the server.

​
How it works

  1. You create an enrollment token in Timbal: a single-use key, valid for 24 hours by default, that lets one server register itself.
  2. You run the installer on the server. It checks the network path, downloads the connector, and registers it as a system service (a Windows service, a systemd unit or a launchd job).
  3. On first start the connector trades the token for its own credential and connects. The token is consumed and can’t be reused.
  4. You list your databases in a local connections.json file, and any file shares in config.json. From then on, Timbal can use them by name.
The connector updates itself when Timbal pushes a new version, and rolls back automatically if the new version can’t connect.

​
What it can reach

Supported platforms: Windows Server 2016 or newer (x64 and ARM64), Linux (x86_64 and aarch64, any distribution) and macOS (Intel and Apple silicon).

​
Coming from the Power BI gateway?

If you’ve set up Microsoft’s on-premises data gateway for Power BI or Fabric, you already know the model: a service on a machine in your network, outbound connections only, cloud queries answered from local data. Most concepts map one to one: Two differences matter when you set it up:
  • Connections live on the server, not in the cloud. There is no “add data source” screen in Timbal where you type a server name and password. You list connections in a file on the gateway server, and Timbal refers to them by name. Your database passwords are never stored in Timbal.
  • Some gateway features aren’t available yet. Timbal Connect can’t go through an HTTP proxy: it needs direct outbound access to api.timbal.ai (see Network requirements). There are no gateway clusters either: each server is its own connector, and the queries and syncs you assign to a connector run only on that server.

​
Before you start

1

Check the network

The server needs direct outbound HTTPS (TCP 443) to api.timbal.ai, with WebSocket allowed and no TLS inspection on that host. This is the most common blocker, so check it first: Network requirements.
2

Get an enrollment token

Ask your Timbal contact for one, or create it with the API: Create enrollment token. The token is shown once and expires after 24 hours unless you set ttl_secs (up to 30 days).
3

Install

Follow the guide for your server: Windows or Linux and macOS.
4

Add your connections

Tell the connector which databases and file shares it may use: Configure connections.

Network requirements

What to ask your IT team for, and how to check it.

Troubleshooting

Every installer message and what to do about it.