# Hyperssh



Hyperssh routes SSH-style access through [HyperDHT](/p2p/reference/building-blocks/hyperdht). This page documents the public binaries installed by [`hyperssh`](https://github.com/holepunchto/hyperssh): `hyperssh` and `hyperssh-fuse`.

## System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hyperssh is not available on Android or iOS.

## Install [#install]

```sh
npm i -g hyperssh
```

For end-to-end setups, the remote side also needs [Hypertele](/p2p/reference/tools/hypertele) so it can expose SSH, SSHFS-backed traffic, or RDP over [HyperDHT](/p2p/reference/building-blocks/hyperdht):

```sh
npm i -g hypertele
```

## Prerequisites [#prerequisites]

Hyperssh does not generate its own keys. The workflows below need a server seed (for [`hypertele-server`](/p2p/reference/tools/hypertele#hypertele-server) on the remote) and, optionally, a client `identity.json`. Generate them with [`hyper-cmd-utils`](https://github.com/holepunchto/hyper-cmd-utils):

```sh
npm i -g hyper-cmd-utils

# Server seed (used as --seed for hypertele-server)
hyper-cmd-util-keygen --gen_seed

# Optional: client identity file (used as -i for hyperssh / hyperssh-fuse)
hyper-cmd-util-keygen --gen_keypair identity.json
```

[`hypertele-server`](/p2p/reference/tools/hypertele#hypertele-server) prints the server public key on start; use that as `-s` for `hyperssh` and `hyperssh-fuse`.

## `hyperssh` [#hyperssh]

[Command source on GitHub](https://github.com/holepunchto/hyperssh/blob/v5.0.4/client.js)

Open an SSH session through a peer exposed over [HyperDHT](/p2p/reference/building-blocks/hyperdht).

```sh
hyperssh -s <peer-key-or-alias> [options]
```

Flags:

* `-s <peer-key-or-alias>`: peer key or resolved host alias to connect to.
  Default: required
* `-u <username>`: remote username.
  Default: the current local OS username
* `-i <identity.json>`: identity file to use for the client.
  Default: off
* `-e <ssh-command>`: remote command to run instead of opening an interactive shell.
  Default: interactive SSH session
* `--rdp`: open a local RDP proxy instead of spawning `ssh`.
  Default: off
* `--help`: show help.

Notes:

* In normal mode, Hyperssh binds an ephemeral local port and runs `ssh -p <port> <user>@localhost`.
* In `--rdp` mode, Hyperssh exposes a local proxy on port `3389` for an RDP client.

Example:

```sh
hyperssh -s <peer-key> -u alice
```

## `hyperssh-fuse` [#hyperssh-fuse]

[Command source on GitHub](https://github.com/holepunchto/hyperssh/blob/v5.0.4/fuse.js)

Mount a remote filesystem locally through SSHFS over [HyperDHT](/p2p/reference/building-blocks/hyperdht).

```sh
hyperssh-fuse -s <peer-key-or-alias> -m <mountpoint> [options]
```

Flags:

* `-s <peer-key-or-alias>`: peer key or resolved host alias to connect to.
  Default: required
* `-u <username>`: remote username.
  Default: the current local OS username
* `-i <identity.json>`: identity file to use for the client.
  Default: off
* `-m <mountpoint>`: local mountpoint for the remote filesystem.
  Default: required
* `--help`: show help.

Notes:

* `hyperssh-fuse` shells out to `sshfs`, so the local machine must already have SSHFS installed.
* As with `hyperssh`, the CLI creates a local ephemeral port and tunnels SSH traffic through it.

Example:

```sh
hyperssh-fuse -s <peer-key> -u alice -m ~/mnt/remote
```

## Common workflows [#common-workflows]

### SSH into a peer by key or alias [#ssh-into-a-peer-by-key-or-alias]

On the remote machine, expose the local SSH service first:

```sh
hypertele-server --seed <server-seed> -l 22
```

If you already know the peer key, connect directly:

```sh
hyperssh -s <peer-key> -u alice
```

If you manage host aliases in your [HyperDHT](/p2p/reference/building-blocks/hyperdht) tooling, use the alias instead:

```sh
hyperssh -s work-server -u alice
```

### Run one remote command without opening an interactive shell [#run-one-remote-command-without-opening-an-interactive-shell]

Use `-e` to pass a single command through the SSH session:

```sh
hyperssh -s <peer-key> -u alice -e "uname -a"
```

### Mount a remote filesystem locally [#mount-a-remote-filesystem-locally]

Expose the remote SSH service first if it is not already running:

```sh
hypertele-server --seed <server-seed> -l 22
```

Create a mountpoint and then use `hyperssh-fuse`:

```sh
mkdir -p ~/mnt/remote
hyperssh-fuse -s <peer-key> -u alice -m ~/mnt/remote
```

### Reach a remote desktop through HyperDHT [#reach-a-remote-desktop-through-hyperdht]

Expose the remote machine's RDP service with [`hypertele-server`](/p2p/reference/tools/hypertele#hypertele-server):

```sh
hypertele-server --seed <server-seed> -l 3389
```

Then open the local RDP proxy:

```sh
hyperssh --rdp -s <peer-key>
```

Connect your RDP client to `localhost:3389`.

## See also [#see-also]

* [Hypertele—`hypertele-server`](/p2p/reference/tools/hypertele#hypertele-server)
* [Hypershell—`hypershell`](/p2p/reference/tools/hypershell#hypershell)
* [Hyperbeam—one-to-one encrypted pipe](/p2p/reference/tools/hyperbeam#hyperbeam)
* [HyperDHT](/p2p/reference/building-blocks/hyperdht)
* [Pear CLI](/pear/reference/pear/cli)