Web-based Terminal for Bash designed for mobile with autocomplete suggestion & gesture typing keyboard
Swell.sh is a terminal for bash designed for use on mobile phone web browser, it comes with convenient features such as autocomplete suggestion and gesture typing keyboard. It is useful for quickly troubleshooting server problems on the go, or in your bed in the middle of the night. If you occassionally use the SSH app on your phone, you may want to give Swell.sh a try!
Diagram:
+-------------+ +--------------+ +--------------+
| | | | | |
| | WebSocket | | spawn | Bash process |
| Client Side +-------------> Server Side +---------->+ |
| <-------------+ | | |
| Browser | | Python | pty | |
| | | +-----------> |
| Chrome / | | API & WS <-----------+ |
| Safari | | | | |
| | | Static File | ptrace | |
| | | +-----------> |
| | | | | |
+-------------+ +--------------+ +--------------+
Swell.sh is a client-server application that 1) spawns a Bash process and 2) opens a HTTP server. It allows users to connect to the server on their mobile browser, then they could interact with the Bash process via the Web terminal UI, kind of similar to using a SSH client App on your phone.
The difference is that the Web-based UI is designed to use on mobile phone and has a virtual keyboard built-into the app that gives features like autocomplete suggestion and swipe gesture (by utilizing information provided by the server process). Think of something like your phone's keyboard trying to suggest the next word you may want to type, but instead of natural language, now it suggests Bash's Tab completion. Take a look at the GIF above to see what it means.
Table Of Content:
Tmux support setting
below)Termux support setting
below)NeoVim Autocomplete support
below)If you like the idea of this project and find it useful, please consider making a donation to support the continued development of Swell.sh via PayPal here
Commercial support/priority bug fixes/custom feature development are available, corporate sponsorship is very welcomed. Please contact via email (see Github Profile)
Requirements:
64-bit Linux
bash
bash
that comes with most Linux distros (eg: Ubuntu 16.04/18.04, Debian stretch 9.7, CentOS 7.6, Fedora 29 are tested) should work with Swell.sh, unless you've overridden the system default one with your own compiled versionpython 3.6+, virtualenv, pip
bash-completion
package - https://github.com/scop/bash-completion (optional, but highly recommended, maybe pre-installed on your system but if not, could be easily installed from most distro's package manager)
ptrace_scope
setting as follow:
In order for Swell.sh to work properly, you have to configure your system's ptrace_scope
to appropriate value. First check:
cat /proc/sys/kernel/yama/ptrace_scope
cap_sys_ptrace
to the python interpreter in your virtualenv, by:
sudo setcap cap_sys_ptrace=eip <path to python interpreter like venv/bin/python>
sudo su
) then echo 0/1 > /proc/sys/kernel/yama/ptrace_scope
git clone https://github.com/wcchoi/swell.sh
cd swell.sh
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt
cd swell.sh
source venv/bin/activate
python app.py # default options: --host=127.0.0.1 --port=8010
<HOST>:<PORT>
, you may need to turn on VPN connection/SSH port forwarding on your phone (see the security notes below)Do NOT expose the server publicly on the Internet without proper authentication and encryption, use it behind a VPN/SSH port forwarding. Otherwise anyone who can access the URL could control your system.
If you plan on exposing the server to Internet, please run it behind a reverse proxy (eg: Nginx, Apache, Caddy), and configure HTTPS and basic authentication (NOTE: unfortunately Basic Auth for WebSocket does not work for iOS Safari, please use other methods) to encrypt the data traffic and limit access. You will need to set the listening interface (--host
flag) to 0.0.0.0
as well when running app.py
Also, please note that Swell.sh itself is not using SSH protocol (it uses WebSocket to interact with a Bash process on the server via pty), and I am no security expert, so it's possible there are places in the code that do not follow the best/strictest security practice. If you have concern/doubt over that, please audit the code and all the third party dependencies and then decide yourself.
If you find vulnerabilities/places where security could be improved, please contact me via email for discussion. Thanks for the help!
These are the current limitations, some maybe fixed in future update. PR welcome!
Swell.sh will detect if the running program is NeoVim, and will hook into NeoVim's API to show autocomplete in the keyboard. The keyboard layout will also adjust for programming language input
** Requires NeoVim version 0.4.0+ **
coc.nvim and TabNine-vim are tested to work with Swell.sh (TabNine provides better autocomplete but is not open-source and requires lots of memory to run)
NOTE:
nvim --listen /some/abs/path <file>
, note you must specify an absolute path (eg: mktemp -u
) for the unix socket, relative path won't work--listen
for it to workIf your system NeoVim installation does not work with Swell.sh, you can optionally install it separately under the repo directory (NOT applicable to Termux):
nvim-linux64.tar.gz
from https://github.com/neovim/neovim/releases into the repo root and extract it./nvim-linux64/
npm install
in ./nvim-linux64/coc.nvim
after cloning to finish the installtion./nvim-linux64/init.vim
and add your vim settings./run-with-env.sh
, this script will add ./nvim-linux64/bin
to PATH and use ./nvim-linux64/init.vim
as the NeoVim config, so that it will not interfere with your global NeoVim config./run-with-env.sh
, you will need to add set-option -ga update-environment ' PATH VIMINIT'
to ~/.tmux.conf
for the env vars to be passed down to the bash spawned by Tmux, PS changing tmux.conf requires killing all existing sessions and restart Tmux for the new settings to take effectNOTE: if you are using Tmux in Termux on Android, you do not need to apply the cap_sys_ptrace
setting below
If you want the autocomplete suggestion to work for bash inside Tmux, please do the following:
(you can skip this if your ptrace_scope
is 0) Add the capability cap_sys_ptrace
to the python interpreter in your virtualenv, by:
sudo setcap cap_sys_ptrace=eip <path to python interpreter like venv/bin/python3>
(If you do not have setcap
command, please google how to install on your system)
Attach to the tmux session by this command:
tmux a -t <session name>
NOTE: you have to attach to the tmux session using the above command in order for Swell.sh to work.
If you create a new session, please detach from it then re-attach to it using the above command. Otherwise the autocomplete suggestion bar will not update.
Tips:
set -g mouse on
to your ~/.tmux.conf
to allow touch in Tmux, useful for switching between windows/panesNOTE: Termux is only tested on the Android devices I have access to (Android Pie/9), and requires 64-bit device
Swell.sh could also be used as an alternative front-end for Termux Bash shell on Android
Install Python3
, bash-completion
in Termux
pkg install python bash-completion
For bash-completion
to work, please add source /data/data/com.termux/files/usr/share/bash-completion/bash_completion
(actual path to bash_completion
script maybe different on your device, you have to find that out) to your ~/.bashrc
(create one if not exist)
Swell.sh depends on Android libc.so
, if you get an error saying libc not found, please add the directory which contain the libc.so
file to LD_LIBRARY_PATH
by eg export LD_LIBRARY_PATH=/system/lib64/:$LD_LIBRARY_PATH
in ~/.bashrc
(eg: /system/lib64/
, you can find that directory path by looking at the rightmost column of the command cat /proc/$$/maps | grep libc
in a Termux Bash shell)
To install and run:
Similar to above, wget/git clone the source repo into a directory, create a venv
(On Termux, you can create virtual env by python -m venv venv
), activate it, pip install -r requirements.txt
, then run python app.py
Then go to localhost:<PORT>
in Chrome
If you want to work with Tmux on Termux,
Attach to the tmux session by this command:
tmux a -t <session name>
NOTE: you have to attach to the tmux session using the above command in order for Swell.sh to work.
If you create a new session, please detach from it then re-attach to it using the above command. Otherwise the autocomplete suggestion bar will not update.
The setcap
/ptrace_scope
in the above section does not apply to Termux
A: Swipe up from space bar
A: Swiping left of Backspace key sends CTRL-W, useful for deleting the suggested word when none of the swipe gesture candidates are correct
A: Swipe up/down/left/right the cursor key (✥) to input up/down/left/right respectively. If swiping down is not detected on your phone, you can also long press that key to input "Down Arrow". Tapping the key will input "Left Arrow"
A: Click 'ctrl', when that key changes to 'CTRL' press the desired alphabet to input Ctrl+alphabet
A: Click ⇧ (Shift) to switch layout to Uppercase, then click 'alt', when that key changes to 'ALT' press the desired alphabet to input Alt+alphabet
A: Click a key 'T+'
A: Click '🌐' Key then input in the text box using the mobile OS's keyboard
htop
/vim
are not using full screen space:A: Try changing font size or running the resize
/resizecons
command, which could be obtained from kbd
package on Ubuntu
export PS1='$ '
See ACKNOWLEDGEMENT.md
Copyright (c) 2019 - 2020 Choi Wai Chung
AGPL version 3