Skip to main content

​
Requirements

  • Windows Server 2016 or newer (or Windows 10/11), x64 or ARM64
  • An account with local Administrator rights
  • The network requirements in place: direct outbound TCP 443 to api.timbal.ai, no TLS inspection
  • An enrollment token, unused and less than 24 hours old (unless created with a longer ttl_secs)

​
Install with the setup file

1

Download the setup file

Download it on the server, or copy it there unchanged:TimbalConnectSetup.cmdYour browser may warn about the download because it’s a script. Choose Keep.
Don’t edit, rename-and-resave, or forward the file through chat apps, email bodies or AI assistants. The installer is embedded at the end of the file, and any of those can strip or re-encode it. The setup then stops with “missing its embedded installer”. Download a fresh copy if in doubt.
2

Unblock it

If Windows says “Windows protected your PC”, or nothing happens on double-click: right-click the file, choose Properties, tick Unblock, then OK.
3

Run it

Double-click TimbalConnectSetup.cmd. In the setup window:
  • Control plane: leave Production selected unless Timbal gave you a different URL
  • Enrollment token: paste your token
  • Download proxy: leave empty unless downloads must go through a proxy. This only affects the download; the service itself always connects directly
Click Install, then Yes on the administrator prompt.
4

Wait for the result

The installer checks the network, downloads and verifies the connector, and registers and starts the timbal-connect service. You get a success or failure message either way. On failure, the message names the cause; look it up in Troubleshooting.
5

Add your connections

Edit C:\ProgramData\TimbalConnect\connections.json for databases and, for file shares, add filesystems to config.json. Then restart the service. See Configure connections.

​
What the setup checks first

Before downloading anything, the setup checks the path the service will use and stops at the first problem, with an explanation: If the firewall rule is approved but not live yet, you can install anyway with -SkipNetworkCheck (see below). The service keeps retrying and connects once the rule lands, as long as the enrollment token hasn’t expired by then. Create the token with a longer ttl_secs if the change may take days.

​
Scripted install

For remote sessions, RMM tools or install scripts, pass the token on the command line. This skips the setup window. Run from an elevated command prompt in the folder that contains the file:
Exit code 0 means installed and started; anything else is a failure, with the cause printed and logged.

​
Locked-down servers

On servers where AppLocker, Windows Defender Application Control (WDAC) or Group Policy blocks unsigned PowerShell scripts, the setup file can’t run and says so. Install the connector binary directly instead; it is its own installer and needs no PowerShell.
1

Download the binary and checksums

On any machine with internet access, download the binary for your server’s architecture and the checksum list:
2

Verify and copy it to the server

The hash must match the line for that file in SHA256SUMS:
3

Install the service

From an elevated command prompt on the server:
The binary copies itself to C:\Program Files\TimbalConnect\, writes its configuration and starts the service.
If application control also blocks running the .exe from your Downloads folder, ask IT to allow it by its SHA-256 hash or to run it from a location your policy allows. This path skips the installer’s network check, so run doctor right after installing.

​
Check that it’s running

In an elevated PowerShell:
You want to see connector enrolled and connected in the log. For a full check of the network and every configured database:

​
Upgrade

The connector normally updates itself when Timbal pushes a new version. To upgrade by hand, run the setup file again and leave the token empty (or run TimbalConnectSetup.cmd with no -Token). Configuration and credentials are kept.

​
Re-enroll

Run the setup file again with a new enrollment token when:
  • The first attempt used a token that had expired, was already used, or belongs to another environment
  • The connector was revoked in Timbal and should come back
The setup window preselects the environment the server is already connected to, so a new token alone keeps it on the same Timbal environment. The server then registers as a new connector. The installer writes the new token into the existing configuration, moves the previous identity aside (state.json becomes state.json.pre-reenroll-<number>, kept as a backup), and restarts the service. Your connections and other settings are kept. If the server had been connected before, its old connector stays offline in Timbal; revoke it.

​
Uninstall

In an elevated PowerShell:
Uninstalling doesn’t revoke the connector in Timbal; it just goes offline. Revoke it too if the server leaves your control: Revoke connector. Reinstalling always needs a new enrollment token.

​
Files on the server

The service runs as NT AUTHORITY\NetworkService. To use Windows-integrated authentication with SQL Server, run it as a domain account instead: see Configure connections.

​
Next steps

Configure connections

Databases in connections.json, file shares in config.json.

Troubleshooting

Installer messages and what to do about them.