🚀 Bring your favorite shell wherever you go through the ssh.

xxh, updated 🕥 2023-02-22 08:14:54

You stuffed your command shell with aliases, tools, and colors but you lose it all when using ssh. The mission of xxh is to bring your favorite shell wherever you go through ssh without root access or system installations.

If you like the idea of xxh click ⭐ on the repo and tweet about it.

Portable. Preparing portable shells and plugins occurs locally, and then xxh uploads the result to the host. No installations or root access on the host required. Security and host environment are a prime focus.	Hermetic. Deleting the `~/.xxh` directory from the remote host will make the remote environment function as if xxh was never there. By default your home is the `.xxh` directory and you can choose the hermetic level of your xxh session.	Careful. No blindfolded copying config files from local to remote host. Following privacy and repeatability practices, the best way is to fork the xxh plugin or shell example and pack your configs into it.
Be open and fork-ready. Every xxh repo could be forked, customized, and reused without waiting for a package management system, xxh release, or any third party packages. Five shells are currently supported and more could be added by the community.	Do more. The xxh packages are not only about shells. Any type of tool or code could be behind an entrypoint. If you want to run browsh on the remote host, just put its portable version as an entrypoint in the xxh-shell.	Chameleon. Switching shells is as easy as possible and you don't have to be locked in to one shell. Choose your current shell based on the task you want to solve: `xxh anyhost +s xonsh` for a Python environment, osquery for simple querying, fish for modern features or time-tested zsh and bash for speed.

Installation methods

PyPi 3

shell script pip3 install xxh-xxh

pipx - good alternative to brew and pip, read comparison

shell script pipx install xxh-xxh

Conda-forge feedstock

shell script conda config --add channels conda-forge conda install xxh-xxh

Homebrew

shell script brew install xxh

Macports

shell script sudo port install xxh

Linux portable binary

shell script mkdir ~/xxh && cd ~/xxh wget https://github.com/xxh/xxh/releases/download/0.8.7/xxh-portable-musl-alpine-Linux-x86_64.tar.gz tar -xzf xxh-portable-musl-alpine-Linux-x86_64.tar.gz ./xxh

Linux AppImage

shell script mkdir ~/xxh && cd ~/xxh wget -O xxh https://github.com/xxh/xxh/releases/download/0.8.7/xxh-x86_64.AppImage chmod +x xxh && ./xxh To run AppImage on Alpine Linux install alpine-pkg-glibc with localedef.

Shells

Currently supported OS for the target host is Linux on x86_64.

| xxh-shell | status | xxh-plugins | seamless | demo | |-----------------------------------------------------------------------|------------|-------------|---------|------| | xonsh | stable | autojump, [+] | xxh.xsh | demo | | zsh | stable | ohmyzsh, p10k, [+] | xxh.zsh | demo | | fish | stable | ohmyfish, fisher, userconfig, [+] | todo | | bash | stable | ohmybash, [+] | xxh.bash | demo | | osquery | beta | | | | | fish-appimage | alpha | | | | | elvish | alpha | | | |

Search xxh shell on Github or Bitbucket or create your shell entrypoint to use another portable shell.

Prerun plugins

Prerun plugins allow you to bring any portable tools, dotfiles, or aliases to your xxh session before running the shell.

Pinned plugins: core (xxh-sudo, xxh-screen, xxh-tmux), dotfiles, docker, python, xxh, vim, zoxide, starship. There is cookiecutter template to create a prerun plugin.

Usage

Use xxh instead of ssh when connecting to Linux hosts without changing ssh arguments: xxh <host from ~/.ssh/config> xxh [ssh arguments] [[email protected]]host[:port] [xxh arguments] xxh local [xxh arguments]

Common examples (use xxh --help to get info about arguments): yaml xxh anyhost # Connect to the host xxh -i id_rsa -p 2222 anyhost # Using ssh arguments: port and key xxh [email protected] +c et # Using EternalTerminal (https://github.com/MisterTea/EternalTerminal) xxh anyhost +s zsh +i # Set the shell and install it without yes/no question xxh anyhost +s xonsh +hhh "~" # Set /home/user as home directory (read Q&A) xxh anyhost +s bash +I xxh-plugin-bash-vim # Preinstall a plugin xxh anyhost +if +q # Force reinstall xxh on the host in quiet mode xxh anyhost +hh /tmp/xxh +hhr # Upload xxh to /tmp/xxh and remove when disconnecting source xxh.zsh anyhost +I xxh-plugin-zsh-ohmyzsh # Connect in seamless mode with ohmyzsh plugin xxh local +s xonsh # Experimental: build xxh environment inplace and without ssh For reusing arguments and simplifying xxh usage (like shortening to xxh anyhost), there is a config file.

Why the plus sign for the xxh arguments? The xxh is using the plus sign for xxh arguments to preserve the ability to use the minus sign for the original ssh arguments. This allows just replacing the first two letters in the ssh command to convert it to the xxh command. Also see the discussion.

Installing xxh packages

bash xxh [+I xxh-package +I ...] [+L] [+RI xxh-package +RI ...] [+R xxh-package +R ...] Different ways to set the xxh package source: yaml xxh +I xxh-shell-example # install from https://github.com/xxh xxh +I https://github.com/xxh/xxh-shell-example # short url for github only, for other sources use examples below or add support xxh +I https://github.com/xxh/xxh-shell-example/tree/mybranch # short url for github only, for other sources use examples below or add support xxh +I xxh-shell-example+git+https://github.com/xxh/xxh-shell-example # long url for any git repo xxh +I xxh-shell-example+git+https://github.com/xxh/xxh-shell-example/tree/mybranch # github only branch support xxh +I [email protected]:githubuser/xxh-shell-example.git # install from private repository using ssh xxh +I xxh-shell-example+path+/home/user/my-xxh-dev/xxh-shell-example # install from local path

Using xxh inplace without ssh connection

This is experimental magic. Please read the text below twice.

If you have shell access on the host or you're in a docker container and you can't ssh to it then you can download and build a hermetic xxh environment inplace. The xxh local command works exactly like xxh remote_host and creates a hermetic environment in ~/.xxh by default.

At this time we don't have portable build tools like git, wget, curl, tar and others which could be required by some xxh package build scripts. When running xxh local it is expected that the tools are present on the host.

To run xxh inplace on Linux x86_64 just copy and paste these bash commands: bash XH=~/.xxh \ && XD=https://github.com/xxh/xxh-portable/raw/master/result/xxh-portable-musl-alpine-Linux-x86_64.tar.gz \ && mkdir -p $XH && cd $XH \ && ( [[ -x $(command -v curl) ]] && curl -L $XD || wget -O- $XD ) | tar zxf - xxh \ && echo 'Usage: ./xxh local [+s xonsh/zsh/fish/osquery/bash]' Next time you're on the host just run ~/.xxh/xxh local and you will enter your xxh environment.

Examples of use cases

Python with pip everywhere without installation

Way 1. Using xonsh

``` xxh anyhost +s xonsh

anyhost> python --version Python 3.8.2 ``` You'll get python-powered xonsh shell with portable python and pip on the host without any system installations on the host. You can install PyPi packages manually or bring them with you automatically by using xxh-plugin-prerun-dotfiles. Also, don't forget about xxh-plugins like zoxide.

Way 2. Using portable python on any xxh shell

``` xxh +RI xxh-plugin-prerun-python xxh anyhost +s zsh

anyhost> python --version Python 3.8.2 anyhost> pip install pandas ``` Using xxh-plugin-prerun-python you'll get a portable Python AppImage which can be used on a host without python and with any xxh shell.

Using docker on host without root access

Try xxh-plugin-prerun-docker: ``` xxh +RI xxh-plugin-prerun-docker xxh anyhost +if

anyhost> xxh-docker-run anyhost> docker ps
CONTAINER ID IMAGE COMMAND anyhost> docker run --rm hello-world | grep Hello Hello from Docker! anyhost> xxh-docker-stop ```

Bring dotfiles to xxh session

There is the xxh-plugin-prerun-dotfiles plugin which creates config files when you go to the host using xxh. You can fork it and create your cozy settings once and forever.

Seamless Oh My Zsh (demo)

shell script source xxh.zsh anyhost +I xxh-plugin-zsh-ohmyzsh +if +q This command brings your current Oh My Zsh session theme to the xxh session. If you need more complex settings just fork the xxh-plugin-zsh-ohmyzsh and hack it.

Read host as a table with osquery

All-in-one portable home

xxh is very agile. You can create your own xxh-shell (the shell part means it has an entrypoint), which can have any portable tools that could help you on the host. Bash xxh-shell is one of these platforms that could be forked and stuffed.

Questions and answers

Development

xxh Development Environment

In the xxh development environment there is a full dockerised environment for development, testing, and contribution. The process of testing and development is orchestrated by xde tool and is as easy as possible.

Vagrant based Plugin Development

To develop plugins, Vagrant supports starting many configurations of virtual machines using Virtualbox.

See the Plugin Development folder for more details

We have teams

If you're in a team it does not mean you have an obligation to do something. The main goal of teams is to create groups of passionate people who could help or support solving complex problems. Some people could be an expert in one shell and a newbie in another shell and mutual assistance is the key to xxh evolution. Ask to join.

Thanks

niess for great python-appimage
probonopd and TheAssassin for hard-working AppImage
Anthony Scopatz, Gil Forsyth, Jamie Bliss, David Strobach, Morten Enemark Lund and @xore for amazing xonsh shell
Roman Perepelitsa for incredible statically-linked, hermetic, relocatable Zsh
Johannes Altmanninger and Fabian Homborg for extensive and portable fish shell

Issues

Replace `setup.py` to `pyproject.toml`

opened on 2023-03-09 14:50:36 by anki-code

subj

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

I was wondering how I can use the same shell in tmux on my server when I use xxh.zsh from my macOS.

opened on 2023-02-09 23:27:02 by yukiyakiZ

Local OS (where xxh is installed): MacOS Destination host OS: Ubuntu xxh version: latest xxh-plugins installed: xxh.zsh

Is there a way to use it for tmux on the server?

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

sshpass: invalid option -- 'o'

opened on 2023-01-05 12:46:58 by Tone866

Local OS (where xxh is installed): Ubuntu 22.04 Destination host OS: Ubuntu 22.04 xxh version: xxh/0.8.12 xxh-plugins installed:

Steps to Reproduce 1. I run xxh host +s bash +i 2. The output log: host:/home/hostuser/.xxh/.xxh/shells/xxh-shell-xonsh not found. Install xxh-shell-xonsh? [Y/n] y Install xxh-shell-xonsh to host:/home/hostuser/.xxh sshpass: invalid option -- 'o' sshpass: invalid option -- 'o' First time upload using rsync (this will be omitted on the next connections) rsync: [Receiver] mkdir "/home/hostuser/.xxh/.xxh/shells/xxh-shell-xonsh/build" failed: No such file or directory (2) rsync error: error in file IO (code 11) at main.c(787) [Receiver=3.2.3] First run xxh-shell-xonsh on host sshpass: invalid option -- 'o' 3. What is the problem I can't xxh into the host, probably because sshpass is not working as expected. sshpass is version 1.09

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

NVM + other bin commands undetected

opened on 2022-06-30 18:25:46 by cyrus01337

Local OS (where xxh is installed): Ubuntu 20.04 Destination host OS: Ubuntu 20.04 xxh version: xxh/0.8.10 xxh-plugins installed: xxh-shell-zsh, xxh-plugin-zsh-ohmyzsh

Steps to Reproduce On the host machine, try to use npm, yarn, nvm or any command that relies on it's bin/ being present in $PATH. zsh will be unable to find the command and output zsh: command not found: foo - when running an installed application as a user with sufficient permissions from the host, it is expected to pick it up.

I'm assuming $PATH is not carried over for security reasons/to prevent jank, there's also the possibility that this may be a zsh issue and am unsure if my mentioning such commands working on the host's zsh nets any favourable insight. Have not tested on other shells.

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

++pexpect-timeout values in config.xxhc are ignored

opened on 2022-05-20 08:53:44 by meermanr

Local OS (where xxh is installed): Ubuntu 20.04 Destination host OS: n/a xxh version: xxh/0.8.10 xxh-plugins installed: none

Problem statement

Some hosts I want to use xxh with have very slow authentication procedures - I can see from ssh -vv that it takes ~20s for the remote end to accept my private key, and additional ~10s to then launch a shell. It an enterprise environment, and likely the delay is caused by audit procedures and mounting network drives etc.

By default xxh only waits 6s for the remote session to begin. By adding ++pexpect-timeout=60 to the command line I can extend this and use xxh without issue. However, I cannot seem to set the same via config.xxhc: it seems to be ignored!

Steps to Reproduce

For this experiment, I spun up a clean Ubuntu 20.04 LTS VM via Vagrant:

bash vagrant init bento/ubuntu-20.04 \ && vagrant up \ && vagrant ssh

and installed the latest portable xxh Linux binaries:

bash cd mkdir xxh cd xxh wget https://github.com/xxh/xxh/releases/download/0.8.10-release2/xxh-portable-musl-alpine-Linux-x86_64.tar.gz tar -xzf xxh-portable-musl-alpine-Linux-x86_64.tar.gz ./xxh

Below is my baseline test, showing the default behaviour of xxh. Note the presence of (timeout=6), and that I have not created a config.xxhc configuration file yet:

bash [email protected]:~/xxh$ time ./xxh +vv example.com </dev/null ssh arguments: ['-o', 'StrictHostKeyChecking=accept-new'] RUN SHELL COMMAND: mkdir -v -p /home/vagrant/.xxh /home/vagrant/.xxh/.xxh/plugins /home/vagrant/.xxh/.xxh/shells Pexpect command (timeout=6): bash -c 'echo -e "xxh_home_realpath=\$(dirname ~/.xxh)/\$(basename ~/.xxh)\n xxh_version=\"dir_not_found\"\n if [[ -d \$xxh_home_realpath ]]; then\n xxh_version=\$([ \"\$(ls -A \$xxh_home_realpath)\" ] && echo \"version_not_found\" || echo \"dir_empty\")\n settings_path=\$xxh_home_realpath/.xxh/xxh_version\n if [[ -f \$settings_path ]]; then\n xxh_version=\$(cat \$settings_path)\n fi\n fi\n echo xxh_home_realpath=\$xxh_home_realpath\n echo xxh_version=\$xxh_version\n echo xxh_shell_exists=\`[ -d \$xxh_home_realpath/.xxh/shells/xxh-shell-xonsh ] && echo \"1\" ||echo \"0\"\`\n echo xxh_home_writable=\`[ -w \$xxh_home_realpath ] && echo \"1\" ||echo \"0\"\`\n echo xxh_parent_home_writable=\$([ -w \$(dirname \$xxh_home_realpath) ] && echo \"1\" ||echo \"0\")\n echo rsync=\`command -v rsync\`\n echo scp=\`command -v scp\`\n echo shell=\`command -v xonsh\`\n echo kernel=\`uname -s\`\n echo arch=\`uname -m\`" | ssh -v "-o" "StrictHostKeyChecking=accept-new" example.com -T "bash -s"'

If I specify ++pexpect-timeout at the command line the timeout notice changes to (timeout=60) as desired:`

bash [email protected]:~/xxh$ time ./xxh +vv ++pexpect-timeout=60 example.com </dev/null ssh arguments: ['-o', 'StrictHostKeyChecking=accept-new'] RUN SHELL COMMAND: mkdir -v -p /home/vagrant/.xxh /home/vagrant/.xxh/.xxh/plugins /home/vagrant/.xxh/.xxh/shells Pexpect command (timeout=60): bash -c 'echo -e "xxh_home_realpath=\$(dirname ~/.xxh)/\$(basename ~/.xxh)\n xxh_version=\"dir_not_found\"\n if [[ -d \$xxh_home_realpath ]]; then\n xxh_version=\$([ \"\$(ls -A \$xxh_home_realpath)\" ] && echo \"version_not_found\" || echo \"dir_empty\")\n settings_path=\$xxh_home_realpath/.xxh/xxh_version\n if [[ -f \$settings_path ]]; then\n xxh_version=\$(cat \$settings_path)\n fi\n fi\n echo xxh_home_realpath=\$xxh_home_realpath\n echo xxh_version=\$xxh_version\n echo xxh_shell_exists=\`[ -d \$xxh_home_realpath/.xxh/shells/xxh-shell-xonsh ] && echo \"1\" ||echo \"0\"\`\n echo xxh_home_writable=\`[ -w \$xxh_home_realpath ] && echo \"1\" ||echo \"0\"\`\n echo xxh_parent_home_writable=\$([ -w \$(dirname \$xxh_home_realpath) ] && echo \"1\" ||echo \"0\")\n echo rsync=\`command -v rsync\`\n echo scp=\`command -v scp\`\n echo shell=\`command -v xonsh\`\n echo kernel=\`uname -s\`\n echo arch=\`uname -m\`" | ssh -v "-o" "StrictHostKeyChecking=accept-new" example.com -T "bash -s"'

However, when I attempt to specify the same via this config.xxhc:

bash [email protected]:~/xxh$ cat ~/.config/xxh/config.xxhc hosts: ".*": ++pexpect-timeout: "60"

I observe that ++pexpect-timeout argument appears in the final argument list ( 👍 ), but not not affect the (timeout=) notice ( 👎 ):

``bash [email protected]:~/xxh$ time ./xxh +vv example.com </dev/null Load xxh config from /home/vagrant/.config/xxh/config.xxhc Load xxh config for host .* Final arguments list: ['++pexpect-timeout', '60', '+vv', 'example.com'] ssh arguments: ['-o', 'StrictHostKeyChecking=accept-new'] RUN SHELL COMMAND: mkdir -v -p /home/vagrant/.xxh /home/vagrant/.xxh/.xxh/plugins /home/vagrant/.xxh/.xxh/shells Pexpect command (timeout=6): bash -c 'echo -e "xxh_home_realpath=\$(dirname ~/.xxh)/\$(basename ~/.xxh)\n xxh_version=\"dir_not_found\"\n if [[ -d \$xxh_home_realpath ]]; then\n xxh_version=\$([ \"\$(ls -A \$xxh_home_realpath)\" ] && echo \"version_not_found\" || echo \"dir_empty\")\n settings_path=\$xxh_home_realpath/.xxh/xxh_version\n if [[ -f \$settings_path ]]; then\n xxh_version=\$(cat \$settings_path)\n fi\n fi\n echo xxh_home_realpath=\$xxh_home_realpath\n echo xxh_version=\$xxh_version\n echo xxh_shell_exists=\[ -d \$xxh_home_realpath/.xxh/shells/xxh-shell-xonsh ] && echo \"1\" ||echo \"0\"`\n echo xxh_home_writable=`[ -w \$xxh_home_realpath ] && echo \"1\" ||echo \"0\"`\n echo xxh_parent_home_writable=\$([ -w \$(dirname \$xxh_home_realpath) ] && echo \"1\" ||echo \"0\")\n echo rsync=`command -v rsync`\n echo scp=`command -v scp`\n echo shell=`command -v xonsh`\n echo kernel=`uname -s`\n echo arch=`uname -m`" | ssh -v "-o" "StrictHostKeyChecking=accept-new" example.com -T "bash -s"' Probably the connection takes more time than expected. Try to increase the timeout by adding "++pexpect-timeout 10" argument. Pexpect details: command: /usr/bin/bash args: ['/usr/bin/bash', '-c', 'echo -e "xxh_home_realpath=\$(dirname ~/.xxh)/\$(basename ~/.xxh)\n xxh_version=\"dir_not_found\"\n if [[ -d \$xxh_home_realpath ]]; then\n xxh_version=\$([ \"\$(ls -A \$xxh_home_realpath)\" ] && echo \"version_not_found\" || echo \"dir_empty\")\n settings_path=\$xxh_home_realpath/.xxh/xxh_version\n if [[ -f \$settings_path ]]; then\n xxh_version=\$(cat \$settings_path)\n fi\n fi\n echo xxh_home_realpath=\$xxh_home_realpath\n echo xxh_version=\$xxh_version\n echo xxh_shell_exists=\[ -d \\$xxh_home_realpath/.xxh/shells/xxh-shell-xonsh ] && echo \\"1\\" ||echo \\"0\\"\\\n echo xxh_home_writable=\[ -w \\$xxh_home_realpath ] && echo \\"1\\" ||echo \\"0\\"\\\n echo xxh_parent_home_writable=\$([ -w \$(dirname \$xxh_home_realpath) ] && echo \"1\" ||echo \"0\")\n echo rsync=\command -v rsync\\\n echo scp=\command -v scp\\\n echo shell=\command -v xonsh\\\n echo kernel=\uname -s\\\n echo arch=\uname -m\\" | ssh -v "-o" "StrictHostKeyChecking=accept-new" example.com -T "bash -s"'] buffer (last 100 chars): b'nfig line 21: Applying options for \r\r\ndebug1: Connecting to example.com [93.184.216.34] port 22.\r\r\n' before (last 100 chars): b'nfig line 21: Applying options for \r\r\ndebug1: Connecting to example.com [93.184.216.34] port 22.\r\r\n' after: match: None match_index: None exitstatus: None flag_eof: False pid: 13198 child_fd: 5 closed: False timeout: 30 delimiter: logfile: None logfile_read: None logfile_send: None maxread: 2000 ignorecase: False searchwindowsize: None delaybeforesend: 0.05 delayafterclose: 0.1 delayafterterminate: 0.1 Answer from host is empty. Try again with +v or +vv or try ssh before xxh.

real 0m6.217s user 0m0.101s sys 0m0.008s [email protected]:~/xxh$ ```

I have also tried using the key=value form of argument in the YAML, which again looked fine in the final argument list, but didn't have any affect:

yaml hosts: ".*": ++pexpect-timeout=60:

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

use of tmate for session sharing

opened on 2022-05-05 13:49:27 by frankenstein91

Is your feature request related to a problem? Please describe. In my working world, we often work on a four-eyes principle. Since the beginning of the pandemic, I have been trying to convince the company of @tmate-io. I think it is a super tool for collaborating even remotely that I would love to use it over xxh.

Describe the solution you'd like Similar to other plugins, I would like to see that tmate could be transferred to the target server and the desired shell could then be used in a shared tmate-sassion.

Describe alternatives you've considered anyone could copy tmate static build by hand and start it after the connection.

Additional context https://tmate.io/

For community: ⬇️ Please click the 👍 reaction instead of leaving a +1 or 👍 comment

Releases

0.8.12 2022-09-29 10:18:07

Maintenance release

0.8.11 2022-09-27 16:20:40

xxh

Preserve symbolic links when copying files via cp. Thanks @meermanr!

xxh-shell-xonsh

Bumped to xonsh 0.13.3

0.8.10 2022-02-13 10:55:08

Package maintenance release

0.8.9 2022-02-13 10:17:32

xxh-x86_64.AppImage

xxh * Added xxh-plugin-prerun-starship to the README. Thanks @izissise!

xxh-dev * The xxh-portable configs were updated

fish-portable * Fish-portable was updated to 3.3.1

0.8.8 2021-12-19 19:28:34

xxh * Fix xxh.zsh on MacOS. Thanks @Moulick!

xxh-shell-elvish * Alpha version released.

0.8.7 2021-03-14 15:31:19

xxh * Added more patterns to support Mac. Thanks @idkjs! * Fixed uppercase alias definitions of ssh hosts. Thanks @jbreicis! * Updated README with better english. Thanks @petarvujovic98 and @0xflotus!

xxh repository * Added tests running in case of creating Pull Request. * Added xxh-portable and xxh AppImage to Github Assets in case of release.

xxh-shell-xonsh * Updated to xonsh 0.9.27

xxh-shell-fish * Updated to fish 3.2.0. Thanks to @frederickjh!

xxh-dev * Changes to support running tests using Github Actions * Moved from xxh/xxh-dev to xxh/xxh/xde deirectory

xxh

Bring your favorite shell wherever you go through the ssh

GitHub Repository

shell ssh xxh linux zsh fish xonsh bash osquery devops openssh ohmybash ohmyzsh ohmyfish powerlevel9k powerlevel10k awesome awesome-ssh fisher hacking-tools