Running on Windows

On Windows, every Rex server can only login as a single account: the account that installs the Windows service. Server Modes, Shared Server and Login Server are for Linux and FreeBSD, and don’t apply here.

Quickstart

This section documents the recommended setup to get up and running quickly. It purposely omits many details about how everything works. We recommend you read the later sections in detail to understand.

1. Install Rex with WinGet, as Installing on Windows shows.

2. Open a terminal with Run as administrator, and install and start Microsoft’s OpenSSH Server:

   Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
   Set-Service sshd -StartupType Automatic
   Start-Service sshd

3. In the same terminal, add your public key, such as the contents of ~/.ssh/id_ed25519.pub. For an administrator account, sshd reads it from this file, and only if only administrators can change it:

   Add-Content C:\ProgramData\ssh\administrators_authorized_keys "ssh-ed25519 AAAA... alice@mac"
   icacls.exe C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant Administrators:F /grant SYSTEM:F

   For a standard account, add the key to ~\.ssh\authorized_keys instead.

4. On your Mac, connect to the PC, where pc is its name or address:

   rex -S ssh://alice@pc ls

   In Rex for Mac, choose Add Remote Host… and enter ssh://alice@pc.

The first connection starts your server, and it keeps running until you stop it. Windows lets SSH in only on networks set to Private. For Tailscale and other ways to connect, see Remote Access.

Server Lifetimes

How you run or install the server determines how long it stays running:

If you only use Rex locally while you’re at your PC, let rex commands autostart the server.

If you want to connect to Rex remotely, start it at boot with rex server install. If you can’t get administrator rights, then start it at sign in with rex server install --user.

CLI-Triggered Servers

Any rex command automatically starts a server if none is running:

rex ls

An automatically started server stops on its own about 10 seconds after its last session and its last connection close. To start one that keeps running until you stop it or sign out, start it explicitly:

rex server start

rex server status, rex server logs and rex server stop work as they do on Linux. See Personal Server.

The server listens on the named pipe \\.\pipe\rex-<SID>, where <SID> is your account’s security identifier. If you set REX_RUNTIME_DIR, the name gets a suffix, so servers with different runtime directories don’t collide.

To keep rex commands from starting a server at all, set REX_AUTOSTART=0.

Starting at Boot

rex server install creates a Windows Service that starts your server at boot and keeps it running while nobody is signed in. Run it from a terminal started with Run as administrator:

rex server install

The service runs as your own account, not as LocalSystem. The command prints each change before it makes it:

• It creates the service RexServer-<SID>, shown as “Rex Server (PC\alice)” in the Services console. It’s set to Automatic (Delayed Start) and runs "<path to rex.exe>" server run with your server flags.
• It grants your account the right to log on as a service.
• It registers “Rex Server” as a source of the Event Log.
• It deletes the sign-in entry, if you added one.

If a server is already running and nothing is using it, the command stops it and starts the service in its place. If the server has sessions or clients, it keeps running, and the service starts at the next boot. The command says which happened.

Running the command again is safe, and keeps your server flags. Run it again after you move rex.exe, such as when you switch between the WinGet zip and the MSI, so that the service runs the new path.

Starting at Sign-In

rex server install --user starts your server each time you sign in to Windows, and needs no administrator rights:

rex server install --user

It adds a value named “Rex Server” to HKCU\Software\Microsoft\Windows\CurrentVersion\Run, which runs rex server start with your server flags. It also starts a server now if none is running. The server stops when you sign out.

Running the command again is safe, and keeps your server flags.

The value shows in the Startup tab of Task Manager, and in Settings under Apps > Startup. If it’s turned off there, Windows skips it, and the command says so rather than turning it back on.

The sign-in entry and the Windows Service can’t both start your server. While the service exists, rex server install --user fails. Remove the service first, as Removing the Service shows.

Server Flags

rex server tailscale on and other changes to a running server last only until it stops. To give your server flags each time it starts, put them after --:

rex server install -- --tailscale
rex server install --user -- --extra-listen tailnet://:7297

The Windows Service runs server run with the flags, and the sign-in entry runs server start with them. With --user, the server that the command starts right away gets them too. rex server run --help and rex server start --help list the flags that each one takes.

What -- does when you run the command again:

The same goes for --user. Moving from --user to the Windows Service carries the sign-in entry’s flags over to the service.

The command checks the flags before it changes anything, and refuses those that the server would refuse. It also refuses these, which don’t work for a server that Windows starts:

A server that’s already running keeps its old flags until it restarts. See Stopping and Restarting. rex server start doesn’t read the sign-in entry, so to restart that server with its flags, stop it and run rex server install --user again, or sign in again.

Administrator Rights

A server that the Windows Service starts runs without administrator rights, even if your account is an administrator. The service starts it with a reduced copy of its token, so every terminal, block plugin and rex.exec program runs as it would after a normal sign-in.

A server that rex server start or any rex command starts gets the same reduced rights, even from a terminal opened with Run as administrator, or from an administrator’s ssh session. If Windows can’t make the reduced token, server startup fails.

rex server run in a terminal opened with Run as administrator keeps full administrator rights. We assume in this scenario you explicitly want this.

Logs

rex server logs shows the log of your server however it was started, the service included:

rex server logs --follow

The log is in %LocalAppData%\rex\servers. Rex clears it before it grows past 50MiB.

The Windows Service also writes to the Application log in Event Viewer, under the source “Rex Server”:

Stopping and Restarting

rex server stop stops your server, however it was started. This ends every program running in its sessions. The server saves its session layouts, and rex ls lists them again once it restarts:

rex server stop

When the service started it, the service stays stopped until the next boot, or until you start it again. To start or stop the service, run these from a terminal started with Run as administrator:

sc.exe start RexServer-<SID>
sc.exe stop RexServer-<SID>

The Services console works too. Look for “Rex Server (PC\alice)“. When the service stops, it gives the server 15 seconds to save its sessions and exit before it ends it.

While the service is stopped, a rex command can start a server on its own, and sc.exe start then fails until that server stops. Set REX_AUTOSTART=0 if you want to keep it from happening.

Removing the Service

rex server uninstall stops the Windows Service, which ends every program running in its sessions, and then deletes it. Run it from a terminal started with Run as administrator:

rex server uninstall

It also unregisters “Rex Server” as a source of the Event Log, unless another account’s service still uses it, and deletes the sign-in entry.

Once a service exists, the command needs administrator rights, even to delete only the sign-in entry. Without a service, it needs none, and a server that the sign-in entry started keeps running. Stop it with rex server stop.

Your account keeps the right to log on as a service, because other services may need it. To remove it, open Local Security Policy (secpol.msc) and go to Local Policies > User Rights Assignment > Log on as a service.

Terminals and Shells

Each terminal runs the first of pwsh.exe and powershell.exe on the server’s PATH, or %ComSpec% if neither is there. There’s no setting to change the default. To run another shell, give it as the command:

rex new -- cmd.exe

A server started by a rex command, by rex server start or by the sign-in entry passes terminals only an allowlist of variables: the usual Windows ones, such as USERPROFILE, APPDATA and ProgramFiles, common toolchain variables, such as JAVA_HOME and GOPATH, and PATH, REX_*, XDG_*, LC_* and the proxy variables. To pass others, start the server with --env:

rex server start --env NAME --env OTHER=value

--env applies only when it starts a new server. To change it, stop the server and start it again. To keep it each time you sign in, give it to the sign-in entry as a server flag:

rex server install --user -- --env NAME

A server that the Windows Service starts gets the system and user variables Windows had when the service started. A variable you add in Settings reaches its terminals after the service restarts. The service refuses --env, because only rex server start takes it.

Terminals have TERM set to xterm-256color, and rex terminfo setup is refused on Windows. Closing a terminal ends every process in it at once.

Not Available on Windows

These parts of Rex need a Unix system: