On-demand Tailscale TCP bridge for non-admin machines. Connect to remote resources securely from locked-down environments.
Working with secure networks often requires VPNs like Tailscale. However, native Tailscale clients require administrator privileges to install and create persistent network interfaces. In many enterprise, corporate, or locked-down environments, users do not have admin rights on their client machines, completely blocking access to critical remote resources via Tailscale.
ts-bridge runs a full, standalone Tailscale node purely in userspace using tsnet. It acts as a local proxy, forwarding TCP traffic (like RDP, SSH, or HTTP) through the encrypted mesh network.
| Native Tailscale | ts-bridge | |
|---|---|---|
| Admin rights on client | Required | None needed |
| Kernel footprint | persistent TUN/TAP | Zero (userspace) |
| Installation | System package | Portable binary |
| Node persistence | Remains on tailnet | Ephemeral (auto-deletes) |
Download the binary from Releases and create a .env file:
TS_AUTHKEY=tskey-auth-kXXXXXXXXX # From Tailscale admin panel
TS_TARGET=100.82.151.104:3389 # Host's Tailscale IP + RDP port
TS_INSTANCE_NAME=office-laptopEnsure Tailscale is running on the target machine and RDP is enabled. The repository includes an automated PowerShell script:
# Run as Administrator
cd scripts\host
PowerShell -ExecutionPolicy Bypass -File .\setup.ps1| Feature | Description |
|---|---|
| Zero-Admin VPN | Connect from heavily restricted laptops without filing an IT ticket. |
| Headscale Support | Compatible with open-source control planes (via TS_CONTROL_URL). |
| Multi-Instance | Run multiple bridges concurrently to connect to different machines. |
| Ephemeral by Default | Leaves no trace. The node is automatically removed from the network when the bridge closes. |
> tailscale up
Error: Administrator privilege is required to install or start the Tailscale service.> ./ts-bridge
+---------------------------------------+
| TAILSCALE BRIDGE v1.3.0 |
+---------------------------------------+
| Host: tsb-office-laptop-a1b2c3 |
| Local: 127.0.0.1:33389 |
| Target: 100.82.151.104:3389 |
+---------------------------------------+
Waiting for connections...Connect using the address from the banner's Local: line. In auto mode the port is hash-derived from the 33389-34388 range, so it differs per machine/instance:
# Read the actual port from the banner above (example shows :33389)
mstsc /v:127.0.0.1:33389 # Windows RDP
xfreerdp /v:127.0.0.1:33389 # Linux RDP
ssh -p 33389 user@127.0.0.1 # SSH targets| Variable | Default | Description |
|---|---|---|
TS_AUTHKEY |
— | Required. Tailscale/Headscale auth key. |
TS_TARGET |
— | Required. Target IP/hostname and port (e.g., 100.x.x.x:3389). |
TS_INSTANCE_NAME |
— | Optional alias to derive a stable local port. |
TS_LOCAL_ADDR |
Auto | Force a specific local address (e.g., 127.0.0.1:4000). |
TS_CONTROL_URL |
— | Set to your Headscale server URL if not using Tailscale SaaS. |
For advanced configuration (timeouts, limits, legacy modes), see the Full Documentation.
┌─────────────────────────┐
│ CLIENT (Non-Admin) │
│ RDP/SSH → :33389 │
│ ↓ │
│ ts-bridge (userspace) │
└────┬────────────────────┘
│ encrypted via WireGuard (DERP/STUN)
┌────▼────────────────────┐
│ HOST (Admin) │
│ Tailscale (native) │
│ ↓ │
│ RDP/SSH Server │
└─────────────────────────┘
Project-bound knowledge lives in docs/ (docs-as-code):
docs/adr/— Architecture Decision Recordsdocs/runbooks/— operational procedures (deploy, RDP host setup, multi-device ops)docs/troubleshooting/— known errors, security audit, release issuesdocs/lessons.md— accumulated gotchas and post-mortems
See CONTRIBUTING.md for development setup, testing, and PR guidelines.
MIT — see LICENSE.