Remote machines (SSH)

Xylem can show the files of another machine, reached with SSH, as a tree: alone, or with this machine next to it in split screen.

Opening one

Type the address in L (Log), or give it to xy on the command line:

user@host: — the home directory; user@host:/srv/www — that directory;
ssh://[user@]host[:port][/path] — with a port, or without a user (as in your ~/.ssh/config).

Xylem runs your own ssh, so what you use in a terminal works the same: ~/.ssh/config (host aliases, ports, ProxyJump), keys, the agent and known_hosts. Nothing needs installing on the other machine: Xylem talks SFTP, which every SSH server has (Linux, BSD, macOS, Windows).

Passwords and questions

When ssh asks for something, the question shows in the footer:

a password or a key’s passphrase: typed hidden; Enter sends it, Esc gives up the connection. Xylem passes it to ssh and keeps nothing.
an unknown host: the host and its key’s fingerprint, to check before answering yes (ssh then remembers it in known_hosts, as usual).

Esc while connecting cancels. With a key and the agent, nothing is asked.

ssh asking for deploy@webserver’s password in Xylem’s footer

What works

The tree, the file window, Filespec, Branch, Showall, tags, the viewer, Ctrl+S and Ctrl+V, Autoview, Info (Alt+I), the display modes (owner shows user and group ids, which is what SFTP sends), Compare and Open (O downloads a copy and opens it here).

Copy brings files here, with their permissions and dates (to the second, as SFTP keeps them); with the screen split, it suggests this machine’s window as the destination. Alt+C (with paths) works too, with paths starting at the remote window’s root.

Split screen: three backups tagged on the remote machine, on the left, about to be copied into a folder of this machine, on the right

Rename (a file, a directory, or the tagged files with a mask) and Makedir work on the remote machine as they do here. A rename never replaces a file without asking; when you say yes, the server replaces it in one step if it can (OpenSSH can), and otherwise Xylem says so and leaves both.

Copy to the remote machine works too: from this machine’s window, with the screen split the remote window is the suggested destination; or type a path of the remote window, or its address (user@host:/srv/www, inside the folder the window was opened on). Each file is written to a temporary file next to the destination, checked for size, given its permissions (without setuid and setgid) and date, and only then put in place; Esc removes the temporary file. Copying within the remote machine works the same way. Symbolic links are not recreated there, and are reported.

Move works in every direction: from here to the remote machine and back (the original is removed only once the copy is in place and checked), and within the remote machine (a rename there). Delete, Prune and the same actions in Usage work too. There is no trash on a remote machine: the question says so, and Oops has nothing to restore. Nothing is removed through a symbolic link: a link is removed as itself. Prune leaves out other disks mounted inside the branch, told apart with the statvfs extension of OpenSSH; on a server without it, Prune is refused.

Attributes take octal permissions (644), as a Unix machine does, even from Windows; New date sets the date, to the second. Neither goes through a symbolic link. Duplicates works there too.

Edit and eXecute are not there yet. F3 rereads a directory; there is no automatic refresh.

F8 in a remote window opens a window on this machine (the folder Xylem started in), so you have both side by side.

The terminal on the remote machine

Alt+X in a remote window opens a shell on that machine (ssh -t), starting in the window’s directory; in a local window, the local shell, as before (each one keeps running while the other is on screen). On Linux and macOS the remote shell reuses the connection already made, so the password is not asked again; on Windows, ssh asks for it in the terminal.

The remote machine’s shell under its tree, after cd logs: the tree has followed it to logs

The tree follows the remote shell’s cd when the shell reports its directory with the OSC 7 sequence. Many systems do it already; for bash, add this to ~/.bashrc on the remote machine:

PROMPT_COMMAND='printf "\033]7;file://%s%s\007" "$HOSTNAME" "$PWD"'

Xylem never types into a remote shell (it cannot see whether a program is running there), and Alt+O and $XY_TAGGED are for local terminals only. Quitting with a remote terminal open asks first.

Some people start tmux (or screen) automatically when they log in over SSH, from ~/.bashrc on the remote machine, so that a dropped connection (a flaky Wi-Fi, a VPN that reconnects) does not kill what was running: logging in again resumes the same session. For example:

if [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ]; then
    tmux attach-session -t remote 2>/dev/null || tmux new-session -s remote
fi

Then Xylem’s remote terminal also opens inside tmux. Everything works, except that the tree does not follow the shell’s cd: tmux sits between the shell and Xylem, keeps the OSC 7 sequence for itself and does not pass it on.

Xylem’s remote shell starts with XY_TERMINAL=1 set, as the local one does, so the login can tell the two apart. Adding that test to the condition keeps tmux for your usual ssh and leaves it out when Xylem connects:

if [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && [ -z "$XY_TERMINAL" ]; then
    tmux attach-session -t remote 2>/dev/null || tmux new-session -s remote
fi

Inside Xylem the shell does not need tmux to survive: it keeps running while Xylem is open, and if the connection drops, the remote window goes with it anyway.

Containers (Docker, Podman)

A container on this machine opens the same way, with no sshd in it:

docker://container — its working directory; docker://container/app — that directory; docker://user@container/app — as that user (docker exec -u).

Xylem runs docker exec and, inside the container, its own sftp-server, the same program an SSH server uses. Most images do not have it: install it in the container (apk add openssh-sftp-server on Alpine, apt install openssh-sftp-server on Debian and Ubuntu, dnf install openssh-server on Fedora), or Xylem says it is missing. The image needs sh, so distroless images are left out.

Everything above works there as on a remote machine, and Alt+X opens a shell in the container, in the window’s folder. With Podman, start Xylem with XY_DOCKER=podman. DOCKER_HOST and docker contexts apply as usual.

Xylem only ever runs docker exec: it does not start, change or download any container. What you write goes into the container, except in folders mounted from this machine (-v): those are this machine’s files.

For Google Drive, S3 and other cloud storage, see Cloud storage.

Keyboard shortcuts