> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network requirements

> What the Timbal Connect server needs from your network, and how to check it before installing

Timbal Connect needs exactly one thing from your network: a **direct, outbound, long-lived HTTPS connection to `api.timbal.ai`**. No inbound ports, no VPN, no public IP.

| Requirement | Value |
| - | - |
| Destination | `api.timbal.ai` (or the host in the URL Timbal gave you) |
| Port | TCP 443, outbound only |
| Protocol | HTTPS (TLS 1.2 or newer) carrying a WebSocket connection (`wss://api.timbal.ai/v1/connect/channel`) |
| Proxy | None: the connection must go out directly |
| TLS inspection | Must be **off** for this host |
| Connection length | Stays open indefinitely. The connector reconnects on its own if it drops |

The installer, the connector binary, its updates and the live connection all use this same host and port, so one firewall rule covers everything. If you've opened a firewall for Microsoft's on-premises data gateway before, this is a much smaller request: no Azure Relay port ranges, no list of Microsoft domains, one host on port 443.

> [!WARNING]
>
> **Opening port 443 is often not enough.** Two common firewall features break the connection even when the port is open:
>
> * **TLS inspection** (also called SSL inspection or HTTPS decryption, available on Fortinet, Sophos, Palo Alto, Check Point and Zscaler, among others). The firewall replaces Timbal's certificate with one signed by your company's own certificate authority. Browsers on your network trust that authority; the connector deliberately does not, so the connection fails. `api.timbal.ai` must be excluded from inspection.
> * **Proxies.** The connector doesn't support HTTP proxies for its connection yet, unlike the Power BI gateway. If your servers only reach the internet through a proxy, the server running Timbal Connect needs a direct-egress exception for `api.timbal.ai`. The installer's proxy option only covers its own downloads.

## What to send your IT team

Copy this into a ticket or email.

> [tab] English
>
> ```text theme={"dark"}
> Subject: Firewall rule for Timbal Connect on <server name>
>
> We are installing Timbal Connect on <server name>. It makes one outbound
> connection to Timbal and needs no inbound access. Please allow, for that
> server only:
>
>   - Outbound TCP 443 to api.timbal.ai (HTTPS + WebSocket, long-lived)
>   - Direct connection, not through a proxy
>   - api.timbal.ai excluded from TLS/SSL inspection
>   - WebSocket upgrades allowed (do not strip the "Upgrade: websocket" header)
>
> Documentation: https://docs.timbal.ai/connect/network-requirements
> ```

> [tab] Español
>
> ```text theme={"dark"}
> Asunto: Regla de firewall para Timbal Connect en <nombre del servidor>
>
> Vamos a instalar Timbal Connect en <nombre del servidor>. Abre una única
> conexión saliente hacia Timbal y no necesita ningún acceso entrante.
> Por favor, permitid solo para ese servidor:
>
>   - Salida TCP 443 hacia api.timbal.ai (HTTPS + WebSocket, conexión persistente)
>   - Conexión directa, sin pasar por proxy
>   - api.timbal.ai excluido de la inspección TLS/SSL
>   - Upgrades de WebSocket permitidos (sin eliminar la cabecera "Upgrade: websocket")
>
> Documentación: https://docs.timbal.ai/connect/network-requirements
> ```

## Check it yourself

The installer runs these checks for you before installing anything and stops with a message naming the layer that failed. To check by hand, run them **on the server itself**: a laptop on the same network may have different firewall rules.

> [tab] Windows (PowerShell)
>
> **1. Port 443 is reachable.** Look for `TcpTestSucceeded : True`.
>
> ```powershell theme={"dark"}
> Test-NetConnection api.timbal.ai -Port 443
> ```
>
> **2. Nothing inspects TLS.** Prints the certificate issuer. It should name a public certificate authority (for example `O=Amazon`). If it names your firewall vendor or your company, or the command fails with a certificate error, TLS inspection is on.
>
> ```powershell theme={"dark"}
> $c = New-Object Net.Sockets.TcpClient('api.timbal.ai', 443)
> $s = New-Object Net.Security.SslStream($c.GetStream())
> $s.AuthenticateAsClient('api.timbal.ai', $null, 'Tls12', $false)
> $s.RemoteCertificate.Issuer
> $c.Close()
> ```
>
> **3. WebSocket gets through.** The first line must be `HTTP/1.1 101 Switching Protocols`. Use `curl.exe`, not `curl`: in Windows PowerShell, `curl` is an alias for a different command.
>
> ```powershell theme={"dark"}
> curl.exe -si --http1.1 --max-time 5 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" https://api.timbal.ai/v1/connect/channel
> ```
>
> **4. Is a proxy configured?** If this shows a proxy server, the server's traffic probably goes through it and needs a direct-egress exception.
>
> ```powershell theme={"dark"}
> netsh winhttp show proxy
> ```

> [tab] Linux / macOS
>
> **1. Port 443 is reachable.**
>
> ```bash theme={"dark"}
> nc -vz -w 5 api.timbal.ai 443
> ```
>
> **2. Nothing inspects TLS.** The issuer should be a public certificate authority (for example `O = Amazon`), not your firewall vendor or your company.
>
> ```bash theme={"dark"}
> echo | openssl s_client -connect api.timbal.ai:443 -servername api.timbal.ai 2>/dev/null | grep -i issuer
> ```
>
> **3. WebSocket gets through.** The first line must be `HTTP/1.1 101 Switching Protocols`.
>
> ```bash theme={"dark"}
> curl -si --http1.1 --max-time 5 -H "Connection: Upgrade" -H "Upgrade: websocket" \
>   -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
>   https://api.timbal.ai/v1/connect/channel
> ```
>
> **4. Is a proxy configured?**
>
> ```bash theme={"dark"}
> env | grep -i _proxy
> ```

After installing, `timbal-connect doctor` repeats the reachability check from the service's point of view. See [Troubleshooting](https://docs.timbal.ai/connect/troubleshooting.md#run-doctor).

## Database side

The connector reaches your databases from the server it runs on, so it needs the usual access from that server: for example TCP 1433 for SQL Server, 5432 for PostgreSQL and 3306 for MySQL, plus UDP 1434 for SQL Server named instances that rely on SQL Browser. These are internal connections and never leave your network. See [Configure connections](https://docs.timbal.ai/connect/connections.md).

## Next steps

> [card] [Install on Windows](https://docs.timbal.ai/connect/install-windows.md)
>
> Setup file, scripted install, and locked-down servers.

> [card] [Install on Linux and macOS](https://docs.timbal.ai/connect/install-linux-macos.md)
>
> Install the service with the script or the binary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.