tollan docs

Quickstart#

This walks you from a fresh account to a service reachable at a public Tollan address. Budget about ten minutes. You'll:

  1. Create an account and an organization.
  2. Register a device and download its bundle.
  3. Install the agent on the device.
  4. Add a route exposing an internal service.
  5. Hit the public address.

Note

Running an ESP32 instead of a Linux/macOS/Windows box? Skip straight to the ESP32 getting started guide — the console steps are the same, but the device runs the library instead of the Go binary.

1. Create your account#

Go to app.tollan.ie, sign up, and verify your email. Your first organization is created automatically — it's the tenant that owns your devices, routes, and billing. Everyone you invite later joins this org with a role (admin, operator, or viewer). See Teams, plans & billing.

2. Register a device#

In the console, create a device:

  • Name — a human label, e.g. home-nas.
  • Architecture — the OS/CPU of the machine that will run the agent, e.g. linux/amd64, linux/arm64, darwin/arm64, or windows/amd64. (For an ESP32 the architecture is cosmetic — you take the certificates, not the binary.)

The device starts in a pending state — it has an identity but hasn't connected yet.

3. Download and install the bundle#

Open the new device and build its bundle. A bundle is a one-time download containing:

  • the agent binary for the architecture you chose,
  • the device's client certificate and private key (its mTLS identity),
  • the CA certificate it uses to verify the relay,
  • a config file and an installer script.

Important

The bundle download link is single-use and expires (about 15 minutes). Download it promptly, and treat the private key inside as a secret.

On the device, extract and run the installer:

bash
tar -xf tollan-home-nas-linux-amd64.tar.gz
cd tollan-home-nas
sudo ./install.sh

The installer sets up a background service (systemd on Linux, install.ps1 on Windows) and starts the agent. The agent reads its config, dials the relay over mutual TLS, and the device flips to online in the console within a few seconds.

You can confirm it's running:

bash
systemctl status tollan-agent
journalctl -u tollan-agent -f

4. Add a route#

A route is what actually exposes a service. On the device page, add one and choose how it's reached:

  • Hostname (SNI) — the service is published at a subdomain like home-nas.tollan.app. Good for HTTPS/TLS services; the relay routes by the TLS SNI on a shared :443.
  • Port — the service is published at a dedicated public port on the relay, e.g. relay.tollan.ie:19000. Good for non-HTTP TCP.

Set the internal target — the address the agent connects to on your side, e.g. 127.0.0.1:8080 for a service on the same box, or 192.168.1.50:80 for a host on the LAN (forwarding mode).

Saving the route pushes it to the relay immediately — no restart. See Routes & exposure for the full detail.

5. Try it#

Hit the public address for your route:

bash
# hostname route
curl https://home-nas.tollan.app/

# port route
curl http://relay.tollan.ie:19000/

The relay demuxes the connection to your device, the agent bridges it to the internal target, and the response comes back through the tunnel. That's a working Tollan tunnel.

Next steps#

  • Lock it down — add access control: IP allowlists, basic auth, OIDC, or client-certificate mTLS.
  • Expose more — add extra routes, or run the agent in forwarding mode to front several LAN hosts from one device.
  • Understand the terms — the Concepts & glossary page defines everything you just used.
  • Go embedded — put the tunnel on a microcontroller with the ESP32 library.