initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,87 @@
+---
+name: tailscale-remote-access
+description: Set up Tailscale on a self-hosted server for remote SSH access from anywhere — no open ports, no dynamic DNS.
+---
+
+# Tailscale Remote Access
+
+Use when the user wants to set up remote terminal/SSH access to a self-hosted server via Tailscale.
+
+## Approach: SSH over Tailscale (default)
+
+Keep existing OpenSSH server. Tailscale provides the encrypted tunnel and stable `100.x.y.z` IP. No port forwarding, no firewall changes.
+
+## Installation
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+```
+
+Installs via apt on Ubuntu/Debian, adds the Tailscale repo and GPG key, starts `tailscaled.service`.
+
+## Authentication
+
+```bash
+sudo tailscale up
+```
+
+This prints a one-time auth URL (`https://login.tailscale.com/a/...`). The URL changes each run.
+
+### Pitfall: agent can't complete browser auth
+
+See `references/agent-auth-workaround.md` for detailed reproduction and the background-process workaround.
+
+In short: the agent installs Tailscale, captures the auth URL from `tailscale status`, gives it to the user, then runs `sudo tailscale up` in the background with `notify_on_complete=true`. The user authenticates in their browser and the background process exits. If the user is on the server's terminal, they can just run `sudo tailscale up` themselves — simpler. For fully automated setups, use `--authkey`.
+
+### Auth keys (pre-authenticated)
+
+For fully automated setups, generate an auth key in the Tailscale admin console and pass it:
+
+```bash
+sudo tailscale up --authkey tskey-client-...
+```
+
+But for one-off setup with an existing account, browser auth is the standard path.
+
+## Post-setup verification
+
+```bash
+tailscale status          # should show the server and other devices on the tailnet
+tailscale ip -4           # the server's Tailscale IP for SSH
+```
+
+## SSH usage
+
+From any other device on the same tailnet with Tailscale installed:
+
+```bash
+ssh user@<tailscale-ip>
+```
+
+The connection goes through Tailscale's WireGuard tunnel. No port 22 exposed to the internet.
+
+## Pitfall: mobile hotspot doesn't bridge Tailscale
+
+A phone running Tailscale + sharing its mobile hotspot does **not** bridge Tailscale traffic to connected devices. The hotspot creates a local NAT — the tethered tablet/laptop gets a private IP from the phone and routes internet through cellular, but Tailscale's virtual interface (`tailscale0`) is separate and not bridged. Each device that needs to reach Tailscale nodes must install its own Tailscale client.
+
+## Tailscale SSH (alternative)
+
+Tailscale can also manage SSH entirely, removing the need for `openssh-server`. Auth is handled by Tailscale ACLs + SSO instead of SSH keys.
+
+### During initial auth
+
+```bash
+sudo tailscale up --ssh
+```
+
+### After tailscale is already authenticated
+
+```bash
+sudo tailscale set --ssh
+```
+
+If the server was set up with plain `tailscale up` (no `--ssh`), use `tailscale set --ssh` to enable SSH post-auth. This is the common case when Tailscale was installed for general connectivity and SSH is added later.
+
+Then from any tailnet device: `ssh user@<hostname>` or `ssh user@<tailscale-ip>`.
+
+If the user explicitly asks for Tailscale SSH, enable it — even if `openssh-server` is already working. The two can coexist.