# Setting up a Private Handler connected to the Public Community Network

> This article is a guide for setting up a private handler that is connected to the public community network. This setup allows for end-to-end encryption between

- Type: Global update from The Things Network
- Author: Hylke Visser
- Published: 2017-01-12
- Updated: 2026-10-06
- Web page: https://www.thethingsnetwork.org/article/setting-up-a-private-handler-connected-to-the-public-community-network

This article is a guide for setting up a private handler that is connected to the public community network. This setup allows for end-to-end encryption between a node and your server.

The server where you are going to deploy the private handler needs a static IP address and/or (sub)domain. In this guide will use the domain `handler.local.thethings.network`. Your firewall needs to allow access to the ports `1904` (for the handler API), `8084` (for the HTTP API) and `1883/8883` (for MQTT/MQTTs) or `5672/5671` (for AMQP/AMQPs). We will rely on the community account server of The Things Network (`account.thethingsnetwork.org`) so that you can use your TTN Account to manage devices in your private handler. If you don't want your handler to use community accounts, you should look at [setting up a private routing environment](https://www.thethingsnetwork.org/article/setting-up-a-private-routing-environment) and use your own account server implementation.

## Preparation

- Install and start [Redis](http://redis.io/download).
- Install and start [RabbitMQ](https://www.rabbitmq.com/download.html) and its [MQTT plugin](https://www.rabbitmq.com/mqtt.html).
  - You should also create a `ttn.handler` exchange using the web interface or with `rabbitmqadmin declare exchange name=ttn.handler type=topic auto_delete=false durable=true`.
- Create a working directory. In this document we will use `~/ttn`. All commands are executed from this directory.
- Download `ttn` (`master` branch) [macOS](https://ttnreleases.blob.core.windows.net/release/master/ttn-darwin-amd64.zip), [64 bit Linux](https://ttnreleases.blob.core.windows.net/release/master/ttn-linux-amd64.zip), [32 bit Linux](https://ttnreleases.blob.core.windows.net/release/master/ttn-linux-386.zip) or [arm Linux](https://ttnreleases.blob.core.windows.net/release/master/ttn-linux-arm.zip).

## Registration

Before we can connect your handler, it needs to be registered in the account server. This links the private handler to your account, making sure that others can't impersonate your private handler to retrieve your data. To do so, we use [`ttnctl`](https://www.thethingsnetwork.org/docs/network/cli/) and add a new `handler` component with the name `mynetwork-handler`:

```sh
ttnctl components add handler mynetwork-handler
  INFO Added network component                  id=mynetwork-handler type=handler
```

Next, we have retrieve an access token that your private handler will use to prove it's identity when it announces with the discovery server. With this announcement, your private handler informs other components in the network about the address and connection security (public key and certificate) of your handler.

```sh
ttnctl components token handler mynetwork-handler
  INFO Got component token                      id=mynetwork-handler type=handler

THE TOKEN THAT WAS GENERATED FOR YOUR HANDLER
```

For security reasons, this access token is only valid for a limited amount of time (about 3 months), so don't forget to rotate it regularly by requesting a new one and reloading your configuration. You probably want to write a script that does this every month or so.

## Handler Configuration

The configuration for the Handler will be stored in `~/ttn/handler/ttn.yml`:

```yaml
id: mynetwork-handler
tls: true
key-dir: handler/
auth-servers:
  ttn-account-v2: "https://account.thethingsnetwork.org"

auth-token: THE TOKEN THAT WAS GENERATED FOR YOUR HANDLER

handler:
  server-address-announce: handler.local.thethings.network
  broker-id: ttn-broker-eu
  mqtt-address: localhost:1883
```

This configuration defines a Handler `mynetwork-handler` on the address `handler.local.thethings.network`. It connects to the Broker `ttn-broker-eu` (located in Europe; you can get a list of Brokers with the command `ttnctl discover broker`).

Now we have to generate a public/private keypair and a TLS certificate for secure communication:

```sh
ttn handler gen-keypair --config ./handler/ttn.yml
ttn handler gen-cert --config ./handler/ttn.yml
```

## Starting the Handler

```sh
ttn handler --config handler/ttn.yml
```

## ttnctl

Configuration of `ttnctl` is done by editing `$XDG_CONFIG_HOME/config.yml` or `~/.ttnctl.yml`:

```yaml
handler-id: mynetwork-handler
```

Now you can register your application to your private Handler. This command creates the necessary information in the handler and publishes the mapping (appID->handlerID) to the discovery server so that other components know where to send your data.

```sh
ttnctl applications register
```

And manage your devices in the same way as you would do on the public community network. Keep in mind that components cache application registrations, so it may take up to 10 minutes before data is sent to your handler.

## Questions or Issues

If you have questions or remarks after following this guide, feel free use the [forum](https://www.thethingsnetwork.org/forum/t/setting-up-a-private-handler/4808) or the `#support` or `#backend` channels on Slack. This is a community-supported guide, so please help each other out.

## What's Next

You should now have a working private handler. Now you should probably do some of the following:

- [Read how to deploy the private handler using docker-compose](https://www.thethingsnetwork.org/article/deploying-a-private-routing-environment-with-docker-compose). Although that guide is meant for complete private backends, you can just skip the steps for all other components and only look at the steps relevant for the handler.
- Periodically update `ttn` to the latest version
- Enable persistence in Redis
- Configure backups
- Secure your MQTT/AMQP broker with usernames and passwords
- Help with development of TTN's open source routing services