Document · Network Access · 9 min read

Enable HTTPS over Tailscale for Kaptain

Use a Tailscale tailnet hostname and a trusted TLS certificate so browser traffic to Kaptain uses an HTTPS URL while remaining scoped to trusted Tailscale devices.

What this enables

Kaptain starts on the local machine and is safest when it is reachable only from the same machine or from trusted devices over Tailscale. Tailscale already encrypts traffic between devices in the tailnet, but browsers still treat plain http:// URLs as not HTTPS. Enabling HTTPS gives the browser a normal https:// URL for Kaptain.

Use the full Tailscale MagicDNS name, such as kaptain-box.example.ts.net. A bare machine name such as https://kaptain-box is not enough for a Tailscale-issued certificate.

Privacy note: Tailscale HTTPS certificates use public Certificate Transparency logs. The certificate name includes the machine name and tailnet DNS name. Rename the machine first if its name contains sensitive information.

Requirements

Tailscale is installed and signed in on the Kaptain machine.
The device you use to open Kaptain is signed in to the same tailnet and has access to the Kaptain machine.
MagicDNS is enabled in the Tailscale admin console.
HTTPS Certificates are enabled in the Tailscale admin console.
Kaptain has an access token configured before it is reachable from another device.

Find the Tailscale name for the Kaptain machine

Open the Tailscale admin console.
Go to Machines.
Open the Kaptain machine.
Copy its full MagicDNS name, for example kaptain-box.example.ts.net.

You can also find the tailnet DNS name on the DNS page in the admin console. The full name is the machine name plus the tailnet DNS name.

Option A: use Kaptain's built-in TLS loading

This option lets Kaptain serve HTTPS directly on its normal port. Kaptain automatically checks for cert.pem and key.pem in the security/tls folder inside the Kaptain data directory when it starts.

1. Create the TLS folder

Linux:

mkdir -p ~/.local/share/kaptain/security/tls

macOS:

mkdir -p "$HOME/Library/Application Support/Kaptain/security/tls"

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Kaptain\security\tls"

2. Generate certificate files for the full MagicDNS name

Replace kaptain-box.example.ts.net with the full name of the Kaptain machine.

Linux:

tailscale cert \
  --cert-file="$HOME/.local/share/kaptain/security/tls/cert.pem" \
  --key-file="$HOME/.local/share/kaptain/security/tls/key.pem" \
  kaptain-box.example.ts.net
chmod 600 "$HOME/.local/share/kaptain/security/tls/key.pem"

macOS:

tailscale cert \
  --cert-file="$HOME/Library/Application Support/Kaptain/security/tls/cert.pem" \
  --key-file="$HOME/Library/Application Support/Kaptain/security/tls/key.pem" \
  kaptain-box.example.ts.net
chmod 600 "$HOME/Library/Application Support/Kaptain/security/tls/key.pem"

Windows PowerShell:

tailscale cert `
  --cert-file="$env:LOCALAPPDATA\Kaptain\security\tls\cert.pem" `
  --key-file="$env:LOCALAPPDATA\Kaptain\security\tls\key.pem" `
  kaptain-box.example.ts.net

If the command requires elevated permission on Linux, run it with sudo, then make sure the user account that starts Kaptain can read the files.

3. Add the Tailscale hostname to Kaptain's allowed hosts

Open kaptain.json in the Kaptain data directory and add the full MagicDNS name to allowed_hosts. If the field is not present yet, add it near the other network settings.

{
  "network_mode": "tailscale",
  "allowed_hosts": ["kaptain-box.example.ts.net"]
}

Kaptain also accepts the configured Tailscale IP, but the browser sends the hostname when you open the HTTPS URL. The hostname belongs in allowed_hosts.

4. Restart Kaptain and open the HTTPS URL

kaptain serve

Open:

https://kaptain-box.example.ts.net:8888

The port stays 8888 unless you changed Kaptain's API port.

Option B: use Tailscale Serve as an HTTPS proxy

This option keeps Kaptain listening on localhost and lets Tailscale Serve expose it through a tailnet HTTPS URL.

Start Kaptain locally and confirm http://localhost:8888 works.
Add the full MagicDNS name to allowed_hosts in kaptain.json.
In another terminal, run:

tailscale serve 8888

Tailscale Serve prints the HTTPS URL that is available inside the tailnet. Keep the Serve process running unless you have configured it as a persistent service on that machine.

Scope note: Use Tailscale Serve for tailnet-only access. Do not enable Tailscale Funnel unless you intentionally want to expose a service beyond your tailnet.

Verify the connection

Open the HTTPS URL from another trusted Tailscale device.
Confirm the browser shows HTTPS for the full MagicDNS name.
Sign in with the Kaptain access token.
Open Model Settings and make a harmless settings change before entering any new provider key.
If the page fails to load, confirm the hostname is in allowed_hosts, Kaptain was restarted, and the second device is connected to Tailscale.

Renew the certificate

Tailscale certificates created with tailscale cert use Let's Encrypt certificates. They expire and must be renewed periodically when you install them as files. Re-run the same tailscale cert --cert-file ... --key-file ... command before expiry, then restart Kaptain so it reads the new files.