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.
@@ -0,0 +1,32 @@
+# Agent-side auth workaround for tailscale up
+
+`tailscale up` blocks until browser auth completes. The agent can't visit the URL.
+
+## Symptom
+
+```
+sudo tailscale up
+# prints: To authenticate, visit: https://login.tailscale.com/a/...
+# hangs forever → timeout after 60-300s
+```
+
+Each run generates a fresh URL. The URL from a previous run is stale.
+
+## Workflow that works
+
+1. `tailscale status` — confirms "Logged out" and prints the current auth URL
+2. Give the URL to the user
+3. `sudo tailscale up 2>&1` in background with `notify_on_complete=true, timeout=300`
+4. User authenticates in browser → process exits → agent notified
+
+## Why foreground fails
+
+Foreground `tailscale up` with timeout will always hit the timeout unless the user is fast. Background + notify_on_complete is the right pattern because the agent gets a push notification when auth completes, rather than polling or timing out.
+
+## Auth key alternative
+
+If the user has a pre-generated auth key from the Tailscale admin console:
+```bash
+sudo tailscale up --authkey tskey-client-<key>
+```
+This completes instantly with no browser step. Generate keys at https://login.tailscale.com/admin/settings/keys