Documentation

Getting started

Download the file for your system from the download section. It is a single program: put it on your own computer and on each host you want to reach, as ~/.local/bin/sshremote on Linux or anywhere on PATH on Windows.

sshremote

With no arguments it opens the home window. On the left is this computer as others reach it: its remote access ID, IP addresses and SSH address, each copied with a click, and the Remote access by ID switch. On the right is one address field for user@host, an alias, an IP or an ID; it says what it reads and opens a terminal, the screen or the files there. Under it are your computers: this computer, favorites, the last opened and the aliases of ~/.ssh/config, each with a sheet for its name, key, saved password and SSH tunnels. The gear opens the settings. What you open goes into the workspace as tabs and panes; each pane switches between terminal, screen and files from its mode menu.

Connecting by SSH

The usual way: the viewer runs ssh -T HOST sshremote --agent, so your keys, agent, jump hosts and ~/.ssh/config work unchanged and nothing else needs to be reachable.

sshremote --gui user@host                 # the workspace
sshremote --gui user@host --open files    # straight to the files
sshremote terminal user@host --split db   # terminal panes, split
sshremote user@host                       # the screen in this terminal (sixel)
sshremote user@host --preset 0            # 0 black and white 5 fps .. 4 true colour 60 fps

A lost connection is tried again in the same mode, keeping the shells; after 30 seconds the pane offers Reconnect or Close.

Connecting by ID through the relay

For a PC without SSH or a fixed address, for example a laptop on Wi-Fi, the way RustDesk works. The PC keeps a lasting 9-digit ID, the same across restarts, and a password its owner sets or generates. A viewer connects with both through the relay.

On the PC to reach

Turn on Remote access by ID on the left of the home window. It shows the ID and the password (copy, show and a new one), a line telling the state and who is connected, each with Disconnect. Remote access settings hold Start with the computer, which installs the Windows service or a systemd user unit (on Windows the service also covers the sign-in and lock screens), your own password, the relay server and a new ID.

The same sheet sets who comes in and what they may do: ask the person at this computer first (a viewer with the right password waits for a click; nobody answering within a minute turns them away), the rights viewers have (keyboard and mouse, clipboard, files, sound and calls, terminals, restart and lock, tunnels; changed for one session in the window shown on this computer, which also ends it), two-step sign-in with an authenticator app's code, being found on this network, and letting viewers on it come straight in (TCP 7073) rather than through the relay.

Straight through the routers. Once the password is right, the two computers look for a path between them that skips the relay (NAT hole punching, as RustDesk does): each asks the relay over UDP which address its router shows, they swap those and their own addresses (IPv6 ones too, which no router changes) inside the sealed connection and try each other's; over IPv6 the same tries open the routers' firewalls. When one works the session moves onto it without a pause, and the relay carries nothing more; a lightning sign in the screen's toolbar says so, a globe while it runs through the relay. When no path is found (routers that change the port for every destination on both sides, or networks without UDP) the session simply stays on the relay. The computer turns this off with Let viewers by ID go straight through the routers in its remote access settings, the viewer under Settings → Connections.

Passwords. Viewers give the lasting password, a one-time password shown beside it (like k7qp-2mz9), or either, as the settings say. A one-time password works for one connection and the minute after it (so a dropped viewer comes back in); then a new one takes its place, and whoever was helped once cannot come back later with it. Who is connected now, and how (through the relay or straight), shows in the window and the icon's menu, each with a way to end it.

Asking without a password. Where the person at the computer turned on Let people without the password ask to come in, someone with only its ID leaves the password empty (in the app, the web page or --password ""). The person there is asked, and both screens show the same six-digit code, made from the key exchange itself: someone in the middle would show another, so they compare it before clicking Let them in. One request at a time.

Only from some addresses. In Who comes in, Only from these addresses takes addresses and ranges (203.0.113.7 192.168.1.0/24 2001:db8::/32): a viewer from anywhere else is turned away before the password is even checked, and told why. Through the relay it is the address the relay sees the viewer from (a relay older than 1.2 does not say, and then nobody comes in past a list); through the web page, the address of its server. sshremote remote-access from … | anywhere sets it from a terminal.

The icon. Once the service is installed, an icon starts with each sign-in: in the notification area on Windows, in the top bar on Linux (GNOME's AppIndicator extension, on in Ubuntu). A click opens SSH Remote; its menu turns remote access on and off, copies the ID, sets who comes in, brings up the window of whoever is connected and starts, stops or removes the service. That window on the computer being viewed stays in the taskbar while someone is connected, so the connection can always be ended there.

On the viewer, the screen's toolbar also locks or restarts the computer, keeps its own keyboard and mouse out and hides its screen from whoever sits there (Windows; Ctrl+P there takes them back), locks it on leaving, calls the person there, and records the screen to an MP4 file.

From any browser, without installing anything: open SSH Remote in the browser (Open in browser at the top of every page here), type the ID and its password, and the screen opens in the page with keyboard and mouse, the files beside it.

On the viewer

Type the ID (digits only) in the address field, then the password, and choose Screen sharing or Files.

From the command line

sshremote remote-access on           # also: status, off, run
sshremote remote-access password     # a new one; password NEW sets yours
sshremote remote-access id           # a new ID
sshremote remote-access install      # start with the computer; uninstall
sshremote remote-access relay HOST   # use another relay
sshremote remote-access ask on       # the person here lets each viewer in
sshremote remote-access allow keyboard files sound   # what viewers may use
sshremote remote-access straight off # always through the relay
sshremote remote-access passwords both  # lasting, one-time, or both
sshremote remote-access viewers      # who is connected; end N ends one
sshremote remote-access service stop # the service, kept installed
sshremote sshremote://ID@sshremote.dev --password P [--code C]
sshremote find                       # computers nearby with remote access on
sshremote wake 3c:52:82:1a:2b:3c     # Wake-on-LAN

Your own relay

The relay is a small program of its own, sshremote-relay, listening on TCP 7071, and on UDP 7071 to tell computers where it sees them from (for straight paths; open both in a firewall). To run your own and keep its IDs in a file:

sshremote-relay --listen 0.0.0.0:7071 --store /var/lib/sshremote/ids.json

Using extensions

Browse the extension list, or open Settings → Extensions in the app (tabs Installed, Browse and Manage). From the command line:

sshremote ext available          # what the signed registry offers
sshremote ext install ID         # install or update
sshremote ext install FILE.sshx  # from a file

The kinds: style packs (pictures and animations behind the terminals), scripts (WebAssembly commands on the selected text, with no file or network access), programs (new sshremote commands such as web and mcp) and resident extensions (status bar items, panels, palette commands, keys and settings). Each request is checked against the permissions in the manifest, shown on the Extensions page.

Building extensions

An extension is a folder with an extension.json manifest. Programs speak JSON-RPC 2.0 over stdin and stdout, one message per line, so any language works. Start from the Rust template, which has a status bar item, a command with a key, a panel, a setting and a form:

sshremote ext new my-extension
sshremote ext dev my-extension

ext dev builds, installs and reloads it in the open app every time a file changes. To share one, pack it with sshremote ext pack DIR OUT.sshx. The manifest, the permissions and the full protocol are in docs/extensions.md.

MCP for AI agents

sshremote mcp HOST (or sshremote mcp --here for this computer) is an MCP server that reads the window in front as text from the accessibility tree and acts on its controls, taking screenshots only when needed. In your agent's MCP configuration:

{"mcpServers": {"remote-pc": {"command": "sshremote", "args": ["mcp", "user@host"]}}}

Security and FAQ