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

# TCP TUNNEL

> Securely Connecting Local Hosted Datasources with SyneHQ Tunnel Client

<Info>
  Want SyneHQ to query data that lives only inside your network or on your laptop? Local Connections let you create a secure tunnel so your database stays private and SyneHQ can still reach it—no firewall surgery, no public exposure.
</Info>

## What you'll do (2 minutes)

* Create a tunnel in SyneHQ to get a secure `token` and `port`
* Point your database connection in SyneHQ to `localhost:<port>`
* Start the Rabbit Tunnel Client (CLI or Docker) to open the secure TCP tunnel

<CardGroup cols={2}>
  <Card title="Open TCP Tunnel in SyneHQ" icon="bridge" href="https://data.synehq.com/tcp-tunnels">
    Create a tunnel to receive your token and port
  </Card>

  <Card title="Add a Connection" icon="database" href="https://data.synehq.com/connections">
    Use localhost and your tunnel port for the host/port
  </Card>
</CardGroup>

## Step-by-step

<AccordionGroup>
  <Accordion title="1) Create a tunnel in SyneHQ">
    * Go to the **Tcp Tunnel** page (sidebar) → **Tunnels**
    * Click **Create Tunnel** to generate your **token** and **port**
    * Copy both; you'll need them for the client

    <Note>
      These credentials only allow access through the secure tunnel—your database itself stays private.
    </Note>

    <img src="https://2839184068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh3pxl4sSLyris6mbVyHW%2Fuploads%2FHbjhlqfQVow9uSqgJXPp%2Fimage.png?alt=media&token=bdbafe2b-3033-4bd8-a971-48540b9e03ce" alt="Create Tunnel UI" />
  </Accordion>

  <Accordion title="2) Add your database connection in SyneHQ">
    * Navigate to **Add Connection**
    * Set the host to `localhost`
    * Set the port to the value from your tunnel
    * Enter DB credentials as usual

    <img src="https://2839184068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh3pxl4sSLyris6mbVyHW%2Fuploads%2FFIzb2KNbNWxJ2g4z0uUP%2Fimage.png?alt=media&token=ed25fdfa-3a9c-4519-a9b1-750d14ac9a15" alt="Add Connection UI" />

    <Info>
      Using `localhost` makes your database appear local to SyneHQ—traffic still flows through the encrypted tunnel.
    </Info>
  </Accordion>

  <Accordion title="3) Install and run the Rabbit Tunnel Client">
    <Tabs>
      <Tab title="Install CLI via curl">
        ```
        curl -fsSL https://github.com/SyneHQ/rabbit.go/blob/sudo/scripts/setup.sh | bash
        ```
      </Tab>

      <Tab title="Install CLI via wget">
        ```
        wget -qO- https://github.com/SyneHQ/rabbit.go/blob/sudo/scripts/setup.sh | bash
        ```
      </Tab>

      <Tab title="Run via Docker">
        ```
        export TUNNEL_TOKEN=your-token

        docker run -d \
          --network=host \
          --name syne-rabbit-tunnel \
          ghcr.io/synehq/rabbit-client:latest \
          tunnel \
            --server rabbit.synehq.com:9999 \
            --local-port 5432 \
            --token "$TUNNEL_TOKEN"
        ```
      </Tab>
    </Tabs>

    <Warning>
      Only run install scripts or containers you trust. Review the script or image if your security policy requires it.
    </Warning>

    Now start the tunnel (replace placeholders). For the CLI binary:

    ```
    rabbit.go tunnel --server rabbit.synehq.com:9999 --token YOUR_TOKEN --local-port 3000
    ```

    * Use your actual `YOUR_TOKEN` or `TUNNEL_TOKEN` from step 1
    * Set `--local-port` to your service's real port (e.g., 5432 for Postgres, 3306 for MySQL)

    <Info>
      That's it—you can now query your private data from SyneHQ without exposing it to the internet.
    </Info>
  </Accordion>
</AccordionGroup>

## What the tunnel does (plain English)

* Creates an encrypted TCP channel from your machine/network to SyneHQ
* Keeps your database private—no inbound rules or public endpoints required
* Automatically reconnects with exponential backoff if the network blips
* Works great for dev and production with health checks and graceful shutdown

## Quick example: Local PostgreSQL

```
export TUNNEL_TOKEN=your-token
rabbit.go tunnel --server rabbit.synehq.com:9999 --token $TUNNEL_TOKEN --local-port 5432
```

SyneHQ can now talk to your local Postgres as if it were in the cloud—query, analyze, visualize.

## Best practices

| Tip                        | Why it helps                                           |
| -------------------------- | ------------------------------------------------------ |
| Store tokens in env vars   | Avoids accidental leakage in shell history and scripts |
| Use limited retries in dev | Keeps logs clean; `--max-retries 0` for dev is fine    |
| Run under a supervisor     | Use Docker, systemd, or PM2 for HA and auto‑restart    |
| Restrict DB credentials    | Least-privilege DB user reduces blast radius           |

```
export TUNNEL_TOKEN=your-token
rabbit.go tunnel --server rabbit.synehq.com:9999 --token $TUNNEL_TOKEN --local-port 3000
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tunnel connects, but DB won't">
    * Verify DB accepts connections from `localhost`
    * Check the **port** matches your service (e.g., 5432 for Postgres)
    * Confirm DB user/password and database name
  </Accordion>

  <Accordion title="SSL or cert errors">
    * Ensure your DB SSL mode matches your setup (disable in local dev if needed)
    * Behind corporate proxies? Check proxy/SSL inspection rules
  </Accordion>

  <Accordion title="High latency or drops">
    * Prefer wired over flaky Wi‑Fi for long‑running sessions
    * Try a closer region or contact support for routing help
  </Accordion>
</AccordionGroup>

<Info>
  For advanced usage, configuration flags, and integration scenarios, see the full Rabbit Tunnel Client guide.
</Info>

<Card title="Tunnel Client Usage Guide" icon="book" href="https://github.com/SyneHQ/rabbit.go/blob/sudo/client/TUNNEL_CLIENT_USAGE.md">
  Explore advanced flags, service configs, and automation patterns
</Card>