Add a server

Join servers, cloud VMs and other headless machines, with a sign-in link or with an auth key from a script.

There are two ways to add a machine nobody sits at:

	Sign-in link	Auth key
Best for	A few servers you set up by hand	Scripts, images, CI and machines that come and go
Runs as	The installed background service	Your own systemd unit
Needs	A browser on any device	A key from the dashboard

The sign-in link doesn't have to be opened on the server itself: open it on your laptop.

On the server, install and connect:

bash

curl -fsSL https://coord.getunderpass.com/download/install.sh | sh

It prints a link:
text
```
To add this machine to your tailnet, open:

    https://app.getunderpass.com/…
```
Open it on any device where you're signed in, and approve the machine.
The server prints Connected as db-prod (100.64.0.21). It stays connected through reboots, because the service starts at boot.

With an auth key

An auth key lets a machine join on its own, with no browser.

Important

Auth keys work with the command-line tool running on its own, not through the background service the install command sets up. Use the steps below on machines where you haven't run the install command, or uninstall the service first (see Install).

1. Create an auth key

In the dashboard, open Auth keys and create one. Choose:

Reusable if several machines will use it; otherwise it works once.
Ephemeral for short-lived machines like CI runners: they're removed after 10 minutes offline.
Pre-approved so machines skip device approval.
Tags, like tag:prod, to give the machines a role in access rules. Tagged machines don't expire.
Auth key expiration: 1 to 90 days, 7 by default.

The key starts with tskey-auth- and is shown once. Keep it in your secret manager. See Auth keys.

2. Download the command-line tool

bash

ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
sudo curl -fsSLo /usr/local/bin/underpass \
  "https://coord.getunderpass.com/download/latest/underpass-linux-$ARCH"
sudo chmod +x /usr/local/bin/underpass

Check it against https://coord.getunderpass.com/download/latest/SHA256SUMS if you like.

3. Join with the key

bash

sudo underpass up --auth-key tskey-auth-xxxxxxxxxxxx --hostname db-prod

It prints registered as db-prod (100.64.0.21, …) and keeps the tunnel up while it runs. --hostname is optional; without it, the machine's hostname is used.

The registration is saved in /var/lib/tailnet. Stop the command with Ctrl+C once it's registered.

4. Keep it running

Create /etc/systemd/system/underpass.service:

ini

[Unit]
Description=Underpass
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/underpass run
Restart=always

[Install]
WantedBy=multi-user.target

Then:

bash

sudo systemctl daemon-reload
sudo systemctl enable --now underpass

underpass run reconnects using the saved registration, so the key isn't needed again.

In a provisioning script

bash

#!/bin/sh
set -e
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
curl -fsSLo /usr/local/bin/underpass "https://coord.getunderpass.com/download/latest/underpass-linux-$ARCH"
chmod +x /usr/local/bin/underpass
timeout 30 underpass up --auth-key "$UNDERPASS_AUTH_KEY" || true   # registers, then stops after 30s
# … write the systemd unit above, then:
systemctl enable --now underpass

Run it as root, with a reusable (and for short-lived machines, ephemeral) key.

Windows servers

Install with UnderpassSetup.exe. When the browser opens for sign-in, finish it from any device, as above.

If it doesn't connect

Message	What to do
`auth key is invalid, expired, or already used`	Create a new key, or a reusable one
`Logged in. An admin needs to approve this machine…`	Approve it under Machines, or use a pre-approved key
`this workspace's plan allows N machines`	Remove a machine or upgrade
`start tunnel (needs root/administrator)`	Run the command with `sudo`

See Troubleshooting for more.