Tailscale Setup Guide

Connecting joins meshTerm's built-in Tailscale node to your Tailnet. Once connected, all SSH, SFTP, and Roam connections to your Tailscale devices route through an encrypted WireGuard tunnel directly from your iPhone or iPad - no separate Tailscale app needed - and the device browser lists your Tailnet's machines with no further setup.

Sign in with Tailscale

The simplest path - no keys to generate, nothing to renew:

1. 1
   Create a profile in meshTerm

   Tap the globe icon in the Sessions tab (or go to Settings → Connections → Tailscale) and create a Tailscale profile.

2. 2
   Tap Sign in with Tailscale

   A browser sheet opens - sign in with the account behind your tailnet (Google, Microsoft, GitHub, Apple, or any identity provider Tailscale supports).

3. 3
   Approve the device if your tailnet requires it

   On tailnets with device approval, meshTerm waits patiently and connects the moment an admin approves - there's a direct link to the admin console right in the app.

Self-hosting? Each profile can point at your own Headscale (or other self-hosted control server) - set the control URL when creating the profile.

Alternative: use an auth key

Prefer not to authenticate through a browser, or automating setup? An auth key joins your Tailnet without any interactive login:

1. 1
   Go to the Tailscale admin console

   Open your browser and go to tailscale.com, then sign in to your account.

2. 2
   Navigate to Auth Keys

   Go to Settings → Personal Settings → Keys. Scroll to the Auth Keys section.

   tailscale.com › Settings › Personal Settings › Keys › Auth Keys
3. 3
   Click Generate auth key

   Enable Reusable so the key survives app restarts. Optionally enable Ephemeral so the node auto-removes from your Tailnet when meshTerm isn't running.

   💡 Reusable + Ephemeral is the recommended combination
4. 4
   Copy the auth key

   Copy the key immediately - Tailscale will only show it once.

5. 5
   Paste it into meshTerm

   Open meshTerm and navigate to the auth key setting.

   meshTerm › Settings › Tailscale › Auth Key

   meshTerm connects to your Tailnet automatically. You'll see the connection status and your Tailscale IP addresses in Settings → Connections → Tailscale.

You don't need this to browse your Tailnet. Once Part 1's connection is up, the device browser lists your machines straight from the tailnet itself. A read-only API token supplements discovery: with one, meshTerm can list your devices by name even when it isn't connected to the tailnet - useful before connecting for the first time on a new profile, when browsing a profile other than the connected one, or when routing through the Tailscale app in Device network mode. You can also skip discovery entirely and add hosts manually by Tailscale IP or MagicDNS name. Tailscale SSH connections work without it.

1. 1
   Go to the Tailscale admin console

   Open your browser and go to tailscale.com, then sign in to your account.

2. 2
   Navigate to API Keys

   Go to Settings → Personal Settings → Keys. Scroll down to the API Access Tokens section.

   tailscale.com › Settings › Personal Settings › Keys › API Access Tokens
3. 3
   Click Generate token

   Give the token a label so you can identify it later.

   💡 Suggested label: meshTerm
4. 4
   Set an expiry

   90 days is a sensible default. You can regenerate the token at any time in the same location.

   ⏱ Recommended: 90 days
5. 5
   Leave permissions as read-only

   meshTerm only needs to list the devices in your Tailnet. No write access is required or requested.

6. 6
   Copy the token

   Copy the token immediately - Tailscale will only show it once. If you lose it, generate a new one.

7. 7
   Paste it into meshTerm

   Open meshTerm, go to your Tailscale profile, and paste the token into its API Token field.

   meshTerm › Settings › Connections › Tailscale

Tailscale SSH enables passwordless, keyless authentication when connecting from meshTerm to a remote host. Instead of a password or SSH key, authentication is handled by Tailscale's identity layer - if your device is on the Tailnet and authorised, you're in.

Requirements

Tailscale SSH is supported on Linux servers running Tailscale v1.30 or later. The host must be running the Tailscale daemon and be a member of the same Tailnet as your iPhone.

Step 1 - Enable Tailscale SSH on the server

Run this command on each Linux server you want to connect to without a password:

# Enable Tailscale SSH on the remote host
sudo tailscale up --ssh

Or if Tailscale is already running and you want to add SSH without changing other settings:

# Add SSH to existing Tailscale configuration
sudo tailscale set --ssh

Verify it's enabled:

# Check Tailscale SSH status
tailscale status

# You should see something like:
# 100.x.x.x   your-server  yourname@  linux   active; offers SSH

Step 2 - Enable Tailscale SSH in your ACL policy (if required)

Depending on your Tailscale plan and ACL configuration, you may need to explicitly permit SSH in your network's access control policy. For personal Tailscale accounts the default policy permits this automatically - you can skip this step.

If you manage a Tailnet with custom ACLs, add the following to your tailscale.com/admin/acls policy:

// Add to your ACL policy at tailscale.com/admin/acls
"ssh": [
  {
    "action": "accept",
    "src":    ["autogroup:member"],
    "dst":    ["autogroup:self"],
    "users":  ["autogroup:nonroot", "root"]
  }
]

Step 3 - Connect from meshTerm

Once Tailscale SSH is enabled on your server, select Tailscale SSH as the authentication method when adding or connecting to a host in meshTerm.

1. 1
   Open meshTerm and go to Hosts

   Your Tailscale peers are listed automatically whenever meshTerm is connected to your tailnet - and, when it isn't, via the optional read-only API token. You can also add a host manually using its Tailscale IP (e.g. 100.x.x.x) or MagicDNS name (e.g. my-server.tail1234.ts.net).

2. 2
   Set Authentication to Tailscale SSH

   When adding or editing a host, select Tailscale SSH as the authentication method. No password or SSH key is needed.

3. 3
   Tap to connect

   meshTerm connects using your Tailscale identity - no password or SSH key required.

Tailscale SSH connection fails

• Confirm tailscale up --ssh was run on the server
• Run tailscale status on the server and check it says offers SSH
• Make sure both devices are on the same Tailnet and showing as connected
• Confirm Tailscale SSH is selected as the authentication method in meshTerm

Connection refused or permission denied

• Check your Tailscale ACL policy permits SSH between your devices
• Verify the username you are connecting as exists on the remote host
• Check journalctl -u tailscaled on the server for connection logs

API token expired

Generate a new token at tailscale.com → Settings → Personal Settings → Keys and update it in meshTerm → Settings → Connections → Tailscale (in the profile that uses it).

Enabling Tailscale SSH by Linux distribution

# Install Tailscale (if not already installed)
curl -fsSL https://tailscale.com/install.sh | sh

# Enable Tailscale SSH
sudo tailscale up --ssh

# Verify
tailscale status

# Install Tailscale
sudo pacman -S tailscale
sudo systemctl enable --now tailscaled

# Authenticate and enable SSH
sudo tailscale up --ssh

# Verify
tailscale status

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
sudo systemctl enable --now tailscaled

# Enable Tailscale SSH
sudo tailscale up --ssh

# If using SELinux, you may need:
sudo setsebool -P tailscale_enabled 1

# Verify
tailscale status

# Install Tailscale
apk add tailscale
rc-update add tailscale
rc-service tailscale start

# Enable Tailscale SSH
tailscale up --ssh

# Verify
tailscale status