hypershell

Spawn shells anywhere. Fully peer-to-peer, authenticated, and end to end encrypted.

Install

npm i -g hypershell

Usage

# Create keys
hypershell-keygen [-f keyfile] [-c comment]

# Create a P2P server
hypershell-server [-f keyfile] [--firewall filename] [--disable-firewall] [--protocol name]

# Connect to a P2P shell
hypershell <server key or name> [-f keyfile]

# Local tunnel that forwards to remote host
hypershell <server key or name> -L [address:]port:host:hostport

# Copy files (download and upload)
hypershell-copy <[@host:]source> <[@host:]target> [-f keyfile]

Use --help with any command for more information, for example hypershell-server --help.

First steps

Keys are automatically created with a default filename on first run.

Otherwise, you can first do:

hypershell-keygen

Just connect to servers (they have to allow your public key):

hypershell <server name or public key>

You could also create a server:

hypershell-server

~/.hypershell/authorized_peers file will be empty, denying all connections by default.
Public keys can be added to the list to allow them in real-time.

Add named peers to the file like for example:

# <public key> <name>
5eehd63aqbc1kzrf5roo89sc3gr4k6hezf5qwh8w44g1xzhmcogo home-pc

Or you can use the --disable-firewall flag to allow anyone to connect, useful for public services like game servers.

Known peers

There will be a file ~/.hypershell/known_peers.

Add named peers to the file like for example:

# <name> <public key>
home cdb7b7774c3d90547ce2038b51367dc4c96c42abf7c2e794bb5eb036ec7793cd

Now just hypershell home (it saves you writing the entire public key).

hypershell-copy

Similar to scp. It works with files, and with folders recursively.

For the next examples, remote_peer is a name that can be added to the known_peers file.

Upload a file from your desktop to a remote server:

hypershell-copy ~/Desktop/file.txt @remote_peer:/root/file.txt

Download a file from a remote server to your desktop:

hypershell-copy @remote_peer:/root/database.json ~/Desktop/db-backup.json

Note: in the future, the @ might be removed.

You can also use the public key of the server directly (without @):

hypershell-copy ~/Desktop/some-folder cdb7b7774c3d90547ce2038b51367dc4c96c42abf7c2e794bb5eb036ec7793cd:/root/backup-folder

Local tunnel

Client

It creates a local server, and every connection is forwarded to the remote host.

In this example, creates a local tunnel at 127.0.0.1:2020 (where you can connect to),
that later gets forwarded to a remote server which it connects to 127.0.0.1:3000:

hypershell remote_peer -L 127.0.0.1:2020:127.0.0.1:3000

Instead of remote_peer you can use the server public key as well.

You can also pass several -L to run multiple local servers that remote forwards:

hypershell remote_peer -L 2020:127.0.0.1:3000 -L 2021:127.0.0.1:3000 -L 2022:127.0.0.1:3000

Server

By default, hypershell-server runs a server with full access, including forwarding to all hosts and ports.

You can run a server with restricted permissions to allow forwarding a specific host and port only.

Let's say you have a local project like a React app at http://127.0.0.1:3000/,
you can create a restricted server to safely share this unique port like so:

hypershell-server --protocol tunnel --tunnel-host 127.0.0.1 --tunnel-port 3000

Or if you want to allow multiple hosts, port range, etc:

hypershell-server --protocol tunnel --tunnel-host 127.0.0.1 --tunnel-host 192.168.0.25 --tunnel-port 1080 --tunnel-port 3000 --tunnel-port 4100-4200

Clients trying to use any different hosts/ports are automatically disconnected.

Multiple keys

To have multiple servers, you need multiple keys.

Generate another key:

hypershell-keygen -f ~/.hypershell/my-server

Now create a new shell server:

hypershell-server -f ~/.hypershell/my-server --firewall ~/.hypershell/my-server-firewall

The client also accepts -f in case you need it.

Restrict server protocols

This is the list of server protocols:

• shell
• upload
• download
• tunnel

By default, all of them are enabled when running a server.

For example, you could limit it to shell only:
hypershell-server --protocol shell

Or only allow file upload and/or download:
hypershell-server --protocol upload --protocol download

Restrict to tunnel only:
hypershell-server --protocol tunnel

For example, if you only allow tunnel, then any attempt from clients to shell into the server will auto disconnect them.

License

Apache-2.0