Remote hosts

Connecting from the Mac

File › Connect (⌘⇧K), then pick or add a host. The app runs your OpenSSH in batch mode, so authentication is your key or agent, and host keys are checked as usual (a changed key is refused, never re-pinned). Over that SSH connection a short bootstrap:

1. looks for ~/.ubiquitty/ubiquitty-host on the server;
2. if it is missing, reports the server’s platform so the app can offer to install it;
3. starts the host if it is not running;
4. hands over to the session protocol, and offers a QUIC upgrade.

A remote shell’s startup output is accepted up to 16 KiB, in lines up to 4 KiB; the bootstrap marks where it ends.

Installing the host

When the server has no host, Connect offers to copy the matching binary that ships inside the app: macOS, Linux x86_64 or Linux aarch64. It asks once per host and never builds on the server. For other platforms it shows instructions.

Installing the host by hand

git clone https://github.com/yaglo/ubiquitty
cd ubiquitty
UBQ_BUILD_ROOT="$PWD/build" ./Scripts/build-host.sh
mkdir -p ~/.ubiquitty
cp build/host/ubiquitty-host ~/.ubiquitty/ubiquitty-host

Building is not installing: Connect looks only at ~/.ubiquitty/ubiquitty-host.

Updating the host

A host older than the client refuses the connection and says so, and the app offers Update: it uploads the matching binary as ~/.ubiquitty/ubiquitty-host.new, checks its SHA-256 and that it runs, and keeps the replaced binary as a backup. If sessions are running, choose Update When They End (the new binary takes over on the first connection after the last session exits) or Update Now (the running sessions end). A failed update changes nothing.

What the host listens on

• An owner-only Unix socket, ~/.ubiquitty/host-<id>.sock, in a directory only you can read. UBIQUITTY_HOME moves the directory.
• A QUIC listener on UDP, on every interface, at a port the system assigns. Whether it is reachable from other networks depends on your firewall.

To	Do
Turn off UDP	start the host with --quic-port -1
Fix the port	--quic-port N
Build without QUIC	configure with -DUBIQUITTY_QUIC=OFF

These apply when a host starts; asking a running host to ensure itself does not change its listener. The listener validates addresses, accepts at most 64 connections, and drops connections that have not presented a one-time token within ten seconds. When UDP is blocked between you and the host, the client stays on SSH after five seconds.

The host has no system service: it starts when a client first needs it and exits when its last session’s shell exits.

From a browser

For a browser on the host machine, see Attach to an existing session. It uses a loopback WebSocket bridge and a scoped token; the browser does not connect to the QUIC listener.

From ubq

export UBQ_REMOTE_TOKEN=<a token issued on that host>
ubq -H user@server ls
ubq -H user@server run -s build -- make

A token issued on one host is never sent to another; remote verbs use UBQ_REMOTE_TOKEN. Issue one on the server with ubiquitty-host token issue --scope <scopes> --label <name>. On a server with nobody attached to answer a consent prompt, --allow-always records a standing consent for that token; revoking the token withdraws it.

Terminal type

If programs on the server do not recognise the terminal, File › Set Up Ubiquitty on Remote Host… gives a command to install the xterm-ubiquitty terminfo entry there.