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

# Forwarder Sink

> Tell-to-Tell forwarding for edge-to-cloud deployments with retry and reconnection.

The forwarder sink sends data to another Tell instance over TCP. Use it for edge-to-cloud deployments where edge nodes collect data locally and relay it to a central server.

## Configuration

```toml theme={null}
[sinks.upstream]
type = "forwarder"
target = "central-tell.example.com:50000"
api_key = "abcdef0123456789abcdef0123456789"
```

| Field     | Default | Notes                                                           |
| --------- | ------- | --------------------------------------------------------------- |
| `target`  | —       | Remote Tell server address as `host:port` (required)            |
| `api_key` | —       | 32-character hex streaming key for the remote server (required) |

## How it works

The forwarder receives batches from the router, rebuilds each FlatBuffer message with:

* The remote server's API key (replacing the local key)
* The original client's source IP preserved in the `source_ip` field

The remote Tell server receives the data as if the original client connected directly, preserving IP-based analytics.

## Protocol

The forwarder uses the same length-prefixed FlatBuffer protocol as Tell's TCP source:

```
[4 bytes: length (big-endian)][N bytes: FlatBuffer batch]
```

The receiving server must have `forwarding_mode = true` on its TCP source to honor the `source_ip` field:

```toml theme={null}
# On the central server
[[sources.tcp]]
port = 50000
forwarding_mode = true
```

Without `forwarding_mode`, the central server would record the edge node's IP instead of the original client's IP.

## Reliability

* **Auto-reconnect** — reconnects automatically if the connection drops, with configurable retry intervals
* **Retry with backoff** — 3 retry attempts per message with 1-second intervals
* **TCP keep-alive** — enabled by default (30-second interval) to detect dead connections
* **Per-message forwarding** — if one message fails, remaining messages in the batch still attempt delivery

## Edge deployment pattern

A typical edge-to-cloud setup:

```toml theme={null}
# Edge node config
[[sources.tcp]]
port = 50000

[sinks.upstream]
type = "forwarder"
target = "central.example.com:50000"
api_key = "abcdef0123456789abcdef0123456789"

[routing]
default = ["upstream"]
```

SDKs connect to the edge node. The edge node forwards everything to the central server. You can also add local sinks for redundancy:

```toml theme={null}
[routing]
default = ["upstream", "local_archive"]
```