Quickstart guides

2023-07-30 (v0.38)

Joining or creating a new network

This short guide explains how to generate an initial configuration for the new node, generating new private keys on the device itself.

Step 1: Bootstrapping the node configuration

A new network and node configuration can be generated by using the “Generate node configuration and keys” link on the application’s configuration screen. This will generate new public and private key pairs for the current node as well as configuration file templates that can now be customised.

Step 2: Configuring the tinc node

The configuration files can be accessed by connecting the device to a computer through Android’s “USB mass storage mode”.

The application’s files are located under [USB storage]/Android/data/org.pacien.tincapp/. The paths in the rest of this document are relative to that directory.

2.1. Network interface configuration

The network interface configuration is specified in network.conf. A minimal configuration specifying an IP address for the node and a network prefix for the VPN can be as short as follows:


# Assign an IP address to this node:
Address =

# Route local traffic for the 10.0.0.x prefix to the VPN:
Route =

2.2. tinc node configuration

The generated host file corresponding to the current tinc node also needs to be edited to make tinc route the traffic from other nodes back to this node.


# ... other automatically generated configuration parameters ...

# Let tinc route traffic for this node's IP address to this node:
Subnet =

Step 3: Replicating node host files

To allow this node to communicate with other ones in the tinc virtual private network, its node host file (files/networks/$netname/hosts/$nodename) needs to be copied to the hosts directory of other nodes. Reciprocally, other node host files need to be replicated to the local node’s files/networks/$netname/hosts/ directory.

Other nodes can be given a publicly reachable Address in their corresponding host file to allow connections to be established. It is also possible to rely on LocalDiscovery if they’re on the same network.

Quite Easily Done.

Joining a network via invitation URL

A network can be joined using a tinc 1.1 invitation URL. The node and its network interface configuration files are automatically created from the data received from the server. Key pairs are also automatically generated and exchanged with the inviting server.

Step 1: Generating an invitation

An invitation can be generated by using the following command on the “server” side:

$ tinc -n <netname> invite [nodename]

An IP address and some routes can be added to the generated invitation file with the Ifconfig and Route parameters:

Name = client
Netname = vpn
ConnectTo = server
Ifconfig =
Route =
Name = server
Ed25519PublicKey = ...
Address = server.example.com

Step 2: Joining using the invitation

The network can be joined from the configuration screen, by tapping on “Join network via invitation URL” and pasting the invitation URL in the appearing input dialog. This will write the node and network configuration files, as well as the generated keys into the tinc network’s configuration directory.

Quite Easily Done.

Migrating from another tinc Android apps

It is possible to migrate from other Android ports of tinc to Tinc App while keeping an existing tinc network configuration with some adjustments, provided that the underlying tinc daemon was operating in router mode using a tun device.

Step 1: Restoring the system’s state

All other VPN applications must be stopped before using Tinc App, regardless of whether they are using the Android VPN API. It is recommended to disable any autostart option in the former ones.

Some applications (such as Vilbrekin’s Tinc GUI) may have required altering system routing tables to operate correctly. Those tables must be restored to their original state before using Tinc App. This can be done simply by rebooting the device.

Step 2: Copying the configuration files and keys

The configuration files can be accessed by connecting the device to a computer through Android’s “USB mass storage mode”.

An existing tinc network configuration can be imported in Tinc App by copying it to [USB storage]/Android/data/org.pacien.tincapp/files/networks/$netname.

Step 3: Adapting the configuration

3.1. Adapting the daemon’s configuration

The tinc daemon configuration file needs to be modified to take some platform specificities into account. In particular, the Device, DeviceType, Interface and ScriptsInterpreter no longer need to be specified in tinc.conf.

3.2. Adapting the node’s configuration

Additionally, an unprivileged port may need to be set in the current host’s file.


# .. other node configuration parameters ...

# Use a port outside of the privileged range,
# because tinc won't run as root anymore.
Port = 1655

3.3. Porting the network interface configuration

The network interface configuration for IP allocation, route and DNS servers definition previously done in hook scripts (such as tinc-up) must converted into parameters in a declarative network interface definition file, named network.conf. Available keys are listed in the network interface section of the manual.

Commands from an example tinc-up file can be translated into corresponding network.conf parameters as follows:

Original tinc-up script:

ifconfig $INTERFACE
ip route add dev $INTERFACE
setprop net.eth0.dns1

Equivalent files/networks/$netname/network.conf:

Address =
Route =
DNSServer =

Quite Easily Done.

Automating VPN connections

Automatically start VPN on boot

The VPN can be started automatically on device boot using the always-on VPN feature available on Android Nougat and newer.

This option can be enabled through the system settings, under the “Network & Internet” / “VPN” categories. A tinc network can then be selected in Tinc App. The chosen one will remain active across device restart until the user disconnects from it through the application’s user interface.

Through third-party apps using Intents

Connections can also be managed from automation and scripting Android applications (such as LlamaLab Automate, Tasker or Locale) by using Intents to start or terminate VPN connections based on time, location, or network availability for example.

A connection can be initiated by starting an Activity using an Intent with the following command, replacing $netname and optionally $passphrase with arbitrary values:

$ am start --user 0 --activity-exclude-from-recents \
    -a "org.pacien.tincapp.intent.action.CONNECT" \
    -d "tinc:$netname#$passphrase"

Similarly, a currently active connection can be terminated by starting an Activity with the following command:

$ am start --user 0 --activity-exclude-from-recents \
    -a "org.pacien.tincapp.intent.action.DISCONNECT"

Quite Easily Done.