Español Portuguese

iroh-ssh

SSH to any machine without ip, behind a NAT/firewall without port forwarding or VPN setup.

# on server
> iroh-ssh server --persist

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330


# on client
> iroh-ssh user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330
# or with certificate
> iroh-ssh -i ~/.ssh/id_rsa_my_cert my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

That's all it takes. (requires ssh/(an ssh server) to be installed)

Installation

cargo install iroh-ssh

Download and setup the binary automatically for your operating system from GitHub Releases:

Linux

# Linux
wget https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.8/iroh-ssh.linux
chmod +x iroh-ssh.linux
sudo mv iroh-ssh.linux /usr/local/bin/iroh-ssh

macOS

# macOS arm
curl -LJO https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.8/iroh-ssh.macos
chmod +x iroh-ssh.macos
sudo mv iroh-ssh.macos /usr/local/bin/iroh-ssh

Windows

# Windows x86 64bit
curl -L -o iroh-ssh.exe https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.8/iroh-ssh.exe
mkdir %LOCALAPPDATA%\iroh-ssh
move iroh-ssh.exe %LOCALAPPDATA%\iroh-ssh\
setx PATH "%PATH%;%LOCALAPPDATA%\iroh-ssh"

Verify that the installation was successful

# restart your terminal first
> iroh-ssh --help

Client Connection

# Install for your distro (see above)
# Connect from anywhere
> iroh-ssh my-user@38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac

Works through any firewall, NAT, or private network. No configuration needed.

Server Setup

# Install for your distro (see above)
# (use with tmux or install as service on linux)

> iroh-ssh server --persist

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

    (using persistent keys in /home/my-user/.ssh/irohssh_ed25519)

    Server listening for iroh connections...
    client -> iroh-ssh -> direct connect -> iroh-ssh -> local ssh :22
    Waiting for incoming connections...
    Press Ctrl+C to exit

or use ephemeral keys

# Install for your distro (see above)
# (use with tmux or install as service on linux)

> iroh-ssh server

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

    warning: (using ephemeral keys, run 'iroh-ssh server --persist' to create persistent keys)

    client -> iroh-ssh -> direct connect -> iroh-ssh -> local ssh :22
    Waiting for incoming connections...
    Press Ctrl+C to exit
    Server listening for iroh connections...

Display its Endpoint ID and share it to allow connection

Connection information

// note: works only with persistent keys
> iroh-ssh info

    Your iroh-ssh endpoint id: 38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac
    iroh-ssh version 0.2.8
    https://github.com/rustonbsd/iroh-ssh

    Your server iroh-ssh endpoint id:
      iroh-ssh my-user@38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac

    Your service iroh-ssh endpoint id:
      iroh-ssh my-user@4fjeeiui4jdm96005255c3begj389xk3aeaeef6cfebd88344aa8c85e1dbfc1ad

How It Works

┌─────────────┐          ┌─────────────────┐          ┌─────────────┐
│     SSH     │─────────▶│  QUIC Tunnel    │─────────▶│  iroh-ssh   │
│   Client    │          │  (P2P Network)  │          │   server    │
└─────────────┘          └─────────────────┘          └─────────────┘
      │                           ▲                            │
      │                           │                            │
      ▼                           │                            ▼
┌─────────────┐          ┌─────────────┐          ┌──────────────────┐
│ ProxyCommand│          │  iroh-ssh   │          │   SSH Server     │
│ iroh-ssh    │──────────│    proxy    │          │ localhost:22     │
│ proxy %h    │          │             │          └──────────────────┘
└─────────────┘          └─────────────┘

1. SSH Client: Invokes iroh-ssh proxy via SSH's ProxyCommand
2. Proxy: Establishes QUIC connection through Iroh's P2P network (automatic NAT traversal)
3. Server: Accepts connection and proxies to local SSH daemon (port 22)
4. Authentication: Standard SSH security end-to-end over encrypted QUIC tunnel

Use Cases

• VNC/RDP over SSH: Securely access graphical desktops remotely
• VisualStudio SSH Extension: Develop on remote machines seamlessly
• Remote servers: Access cloud instances without exposing SSH ports
• Home networks: Connect to devices behind router/firewall
• Corporate networks: Bypass restrictive network policies
• IoT devices: SSH to embedded systems on private networks
• Development: Access staging servers and build machines

Commands

# Get your Endpoint ID and info
> iroh-ssh info

# Server modes
> iroh-ssh server --persist          # Interactive mode, e.g. use tmux (default SSH port 22)
> iroh-ssh server --ssh-port 2222    # Custom SSH port (using ephemeral keys)

# Service mode
> iroh-ssh service install                   # Background daemon (linux and windows only, default port 22)
> iroh-ssh service install --ssh-port 2222   # Background daemon with custom SSH port
> iroh-ssh service uninstall                 # Uninstall service

# Client connection
> iroh-ssh user@<ENDPOINT_ID>                    # Connect to remote server
> iroh-ssh connect user@<ENDPOINT_ID>            # Explicit connect command, works with all standard ssh params and flags

Security Model

• Endpoint ID access: Anyone with the Endpoint ID can reach your SSH port
• SSH authentication: SSH key file, certificate and password auth are supported
• Persistent keys: Uses dedicated .ssh/iroh_ssh_ed25519 keypair
• QUIC encryption: Transport layer encryption between endpoints

Status

• Password authentication
• Persistent SSH keys
• Linux service mode
• Add howto gifs
• Add -p flag for persistence
• Windows service mode
• (almost) all ssh commands supported
• MacOS service mode

License

Licensed under either of Apache License 2.0 or MIT license at your option.