Set up RDP Gate,
then sign in from anywhere.

Before you start

Setup takes about 15 minutes. Have these ready:

Download everything from the Releases page, and check files against SHA256SUMS.txt there.

Part 1 · Server: the Windows PC

Everything in this part happens on the PC you want to reach from outside.

1. Make a GitHub token for the beacon

   Your PC has no fixed address, so it publishes its current IP in a secret gist, encrypted and signed. To do that it needs a token.

   1. Sign in to GitHub with the account you'll use only for RDP Gate.
   2. Open Settings → Developer settings → Fine-grained tokens → Generate new token.
   3. Under Account permissions, set Gists to Read and write. Leave everything else at No access.
   4. Generate the token and copy it. You paste it into RDP Gate Server right after Setup.

   Why a separate account? A Gists token can read and change every gist on its account, and GitHub can't narrow it to one. On an account used only for this, a leaked token exposes nothing else.

2. Run the server Setup

   Run RDP-Gate-Server-Setup-<version>.exe. At the SmartScreen prompt choose More info, then Run anyway (the build isn't Microsoft-signed yet). The wizard asks for:

   Browser sign-in with my domain	Leave it unticked unless you want browser sign-in. If you tick it, the next page explains what you need and asks for the domain; afterwards RDP Gate Server shows the exact DNS records and checks them. The desktop app never needs a domain.
   Forward ports on my router	Keep ticked. Setup asks the router (UPnP) to forward TCP 47443 and 3389 to this PC. RDP Gate never uses ports 80 or 443, so a web server or VPN can keep them.
   Account lockout policy	Keep ticked. 10 wrong Windows passwords lock that account for 15 minutes.
   Stop this PC sleeping	Keep ticked on a desktop. A sleeping PC can't answer, and nothing on the internet can wake it. On a laptop this only warns.
   Show the service's status	Keep ticked. An RDP Gate icon next to the clock shows whether the service is running; click it to open RDP Gate Server.
   Also open UDP	Off by default. UDP makes Remote Desktop smoother, but UDP senders can be forged. Leave it off unless you need it.
   When to close Remote Desktop	Now if you're sitting at the PC. After my first sign-in if you're installing over Remote Desktop: closing it now would disconnect you, with no enrolled computer to get back in. Setup picks this one for you when it sees a Remote Desktop session.

   Setup then turns on Remote Desktop with Network Level Authentication, creates the server identity and starts the RDPGate Windows service, without opening any console window. With Now it first blocks inbound traffic in Windows Firewall, and stops if Group Policy still exposes Remote Desktop (it tells you in a message; the details are in C:\ProgramData\RDPGate\logs\setup.log).

   At the end RDP Gate Server opens with a Finish setting up list. Its first step is the beacon: choose Set up…, paste the token from step 1 and choose Save and publish. The next ones are the 6-digit codes (below) and your computers.

   Installing over Remote Desktop? With After my first sign-in, Remote Desktop stays reachable as before. Once one of your computers has signed in through RDP Gate and connected to Remote Desktop, the service closes it to everyone else by itself. Your address keeps its own opening, so that session stays up. rdpgate-server status shows Protection: PENDING until then. To close it earlier, run rdpgate-server protect.

   Prefer a script? (portable zip)

   Unzip RDP-Gate-<version>-Windows-Server.zip, open PowerShell as Administrator in that folder and run:

   Set-ExecutionPolicy -Scope Process Bypass
   .\install-server.ps1

   Switches: -Protect Now|AfterSignIn (default: AfterSignIn inside a Remote Desktop session, otherwise Now), -DomainSetup or -PublicHost rdp.example.com (with -CertFile and -KeyFile), -AllowUdp, -Lan On|Off, -SkipLockout, -SkipSleep, -NoBeacon, -NoTotp, -RdpPublicPort 53389, -ListenPort 8443.

3. Set up 6-digit codes

   In RDP Gate Server's Finish setting up list, choose Set up… next to the 6-digit codes: a QR code appears. Scan it with your authenticator app and type the code it shows. (A reinstall keeps the codes you already have.) To do it later or again, open RDP Gate Server > 6-digit codes, or run in PowerShell as Administrator:

   rdpgate-server totp-setup            # add --invert if the QR code won't scan
   rdpgate-server totp-setup --force    # replace the secret (old codes stop working)

   Or open RDP Gate Server > 6-digit codes from the Start menu:

   RDP Gate Server · 6-digit codes

   

4. Check the router

   Usually there's nothing to do. Check what happened:

   rdpgate-server status    # identity, beacon, router forwards, warnings
   rdpgate-server router    # try the router forwards again and report

   If the router refused UPnP, forward these by hand in its admin page, to this PC's LAN address:

   External	To this PC	Purpose
   TCP 47443	47443	Sign-in
   TCP 3389	3389	Remote Desktop. Windows Firewall keeps it closed until someone signs in.

   Either way, give the PC a reserved (fixed) address in the router's DHCP settings, so the forwards keep pointing at it.

   If status reports carrier-grade NAT, your ISP shares one public IP among many customers, and nothing from outside can reach your PC. Ask the ISP for a public IPv4 address. It's often free.

Part 2 · Client: your Mac or PC

Do this once on every computer you want to connect from. Each gets its own key, so you can remove one without affecting the others.

1. Install the app

   Mac

   Open RDP-Gate-<version>-macOS.dmg and drag RDP Gate to Applications. The first time, right-click it and choose Open (the build isn't notarized yet). Install Microsoft's Windows App too.

   Windows

   Run RDP-Gate-Client-Setup-<version>.exe. It installs just for you, with no administrator rights, and adds RDP Gate to the Start menu. At SmartScreen choose More info → Run anyway.

2. Create this computer's key

   Open RDP Gate. On Set up this computer, fill in:

   • This computer: a short name, e.g. macbook.
   • Windows user: your Windows account on the server (optional; it's pre-filled in Remote Desktop).
   • Passphrase: encrypts the key on this computer. It never leaves it and can't be recovered, so keep it in your password manager.

   Choose Create device key.

   RDP Gate

   

3. Enroll it on the server

   The app now shows Enroll this computer with one command. Choose Copy command. On the server, open RDP Gate Server > Computers and paste it into Add a computer, or paste and run it in PowerShell as Administrator:

   rdpgate-server device-add macbook rdpgate-ed25519:3q2+7w…

   Paste the whole copied line: the key is the long word starting with rdpgate-ed25519:, and it comes from the computer you'll connect from, not from the server.

   The server shows the device's fingerprint. Check that it matches the fingerprint shown in the app. If it doesn't, the command was changed on the way: don't continue.

   RDP Gate

   

   RDP Gate Server · Computers

   

4. Paste the server card into the app

   The server also prints a server card, a line starting with rdpgate-card:. Paste it into the app and choose Save server card.

   The card tells the app how to find your PC, and pins the server's identity key so that a fake server is caught. Keep it private: it can't sign in by itself, but it reveals where your PC is. Print it again any time with rdpgate-server card.

rdpgate init --name macbook --username you     # prints the device-add command
rdpgate card rdpgate-card:…                     # after running device-add on the server
rdpgate show                                    # fingerprints, pinned server, enroll command

Part 3 · Signing in and connecting

Test from outside your home network first, for example over your phone's hotspot. From inside, see "is not a public address".

1. Sign in from the app

   Enter your passphrase and the current 6-digit code, then choose Sign in and open Remote Desktop. In a few seconds the app:

   1. reads and decrypts the beacon to find your PC's current address;
   2. makes the server prove its identity key before sending anything;
   3. signs in with this computer's key and your code;
   4. checks the Remote Desktop certificate is your PC's;
   5. opens Remote Desktop with your settings. Log in to Windows with your Windows password as usual, or let it be filled in (see Remote Desktop settings).

   RDP Gate

   

   RDP Gate

   

   The app shows Open for <your IP> and a countdown. You have 10 minutes to start Remote Desktop. While you're connected, access stays open (up to 12 hours). Both times can be changed in RDP Gate Server → Overview → Time limits. If your computer has both IPv6 and IPv4, signing in opens both addresses, and locking closes both. If the Remote Desktop window closed, choose Open Remote Desktop to reopen it.

2. Remote Desktop settings and your Windows password

   Open Remote Desktop settings below the sign-in card. Changes are saved straight away and apply every time RDP Gate opens Remote Desktop:

   • Display: full screen, full screen on all monitors, or in a window (match this screen or a custom size); what happens when the window is resized; display scale; colour depth; where Windows key combinations go; the connection bar.
   • This computer's devices: clipboard, sound (here, on the remote computer, or off), microphone, cameras, drives, printers and smart cards. By default only the clipboard and sound are shared.
   • Experience: connection speed, desktop background, font smoothing, animations and themes, and reconnecting if the connection drops.

   Remember my Windows password keeps your Windows user name and password in Windows Credential Manager or the macOS Keychain, never in a file. Forget saved password removes it.

   • Windows: Remote Desktop signs in by itself, as with its own Remember me. On a PC joined to a work domain, Windows policy may refuse saved credentials; Remote Desktop then just asks.
   • Mac: Windows App can't take a password from another app, so it still asks. RDP Gate fills in the user name, and Copy Windows password puts the password on the clipboard to paste (cleared after 45 seconds).

3. Close access when you're done

   Choose Close access now in the app, or run rdpgate lock. Otherwise access closes by itself a few minutes after you disconnect.

   While access is open, anyone behind the same public IP (hotel Wi-Fi, an office, a mobile carrier) can reach the Windows login screen. They still need your Windows password, but close access when you leave.

4. Or from the command line

   rdpgate connect                 # asks for passphrase and code, then opens Remote Desktop
   rdpgate connect --no-launch     # only open the firewall; prints the address and .rdp file
   rdpgate connect --address 203.0.113.7:47443 # try this address first
   rdpgate connect --keep-signed-in --follow # stay signed in; move access when the IP changes
   rdpgate forget                  # sign this computer out: passphrase and code next time
   rdpgate settings                # show the Remote Desktop settings
   rdpgate settings --display all-monitors --drives on   # change them (--help lists all)
   rdpgate password                # remember your Windows password (--forget, --copy on a Mac)
   rdpgate lock                    # close access for this network now

Browser sign-in with a passkey (optional)

Use this from a computer without the app, such as a work laptop or a friend's PC. Sign in with Touch ID, Face ID, Windows Hello or a security key.

Browsers tie passkeys to a domain name, never an IP address, so you need:

• A domain you control, e.g. example.com, from any registrar or Cloudflare.
• A DNS "A" record for a name under it, e.g. rdp.example.com, pointing at your home's public IP.
• Dynamic DNS if your home IP changes. Most registrars and routers have it built in ("DDNS").
• A certificate for that name, as PEM files you renew. RDP Gate doesn't fetch one: Let's Encrypt only checks ports 80 and 443, which RDP Gate never uses. Get one with a DNS check instead (win-acme, or certbot with your DNS provider's plugin).
• Port 47443 on your router reaching the PC (already done for the app). The sign-in page is at https://rdp.example.com:47443/….

The desktop app doesn't need any of this.

1. Run the guided domain setup

   Tick browser sign-in in Setup, or later open RDP Gate Server > Browser sign-in > Set up with my domain. From PowerShell as Administrator it's:

   rdpgate-server domain-setup

   It walks you through four steps:

   1. Domain name. Enter e.g. rdp.example.com.
   2. DNS records. It finds your public addresses and shows the exact records to create: type A for IPv4 and, if you have IPv6, AAAA (name, value, TTL). Then it checks them until they're right. It warns about a Cloudflare proxy (set it to DNS only) and any record that points somewhere else.
   3. Certificate. Enter the certificate file (PEM, full chain) and its private key. It checks they match and cover your domain. Renewed files are picked up within an hour, no restart needed.
   4. Turn it on. It saves the settings and restarts the service (signed-in computers keep their access). Then it prints your sign-in page and offers a link for your first passkey.

   Your devices, passkeys, beacon and other settings are kept. To turn browser sign-in off again: rdpgate-server domain-setup --remove.

2. Find your sign-in page

   rdpgate-server status
   # Browser login:  https://rdp.example.com/Xk3…random…/

   The page lives at a random path, so scanners never find it. Bookmark the full URL on each device you'll use. The domain alone shows nothing.

3. Add a passkey

   rdpgate-server passkey-enroll     # prints a one-time link, valid 15 minutes

   Open the link on the device whose passkey you want to add (your iPhone, Mac or PC), give it a name and choose Create passkey. Treat the link like a password. Repeat for each device. passkey-list and passkey-remove NAME manage them.

4. Sign in from the browser

   Open your bookmarked sign-in page and choose Sign in with passkey. The page then shows:

   • Opened for: your network's public IP;
   • Connect to: the address for your Remote Desktop app, or use Download .rdp file;
   • The certificate fingerprints (SHA-256 and SHA-1). When Remote Desktop shows the PC's certificate, they must match. If they don't, someone is intercepting the connection: don't log in.

   Choose Close access now on the same page when you're done.

Day-to-day operation

Run these on the server in PowerShell as Administrator.

Troubleshooting

Still stuck? Open an issue on GitHub with the relevant lines from the log. Report security problems privately: see SECURITY.md.