[Español](README_es.md) [Portuguese](README_pt.md)
# iroh-ssh
[](https://crates.io/crates/iroh-ssh)
[](https://docs.rs/iroh-ssh)
[](LICENSE)
**SSH to any machine without ip, behind a NAT/firewall without port forwarding or VPN setup.**
```bash
# 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
```bash
cargo install iroh-ssh
```
Download and setup the binary automatically for your operating system from [GitHub Releases](https://github.com/rustonbsd/iroh-ssh/releases):
Linux
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# restart your terminal first
> iroh-ssh --help
```
---
## Client Connection
```bash
# 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.
<br>
---
## Server Setup
```bash
# 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
```bash
# 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
<br>
## Connection information
```bash
// 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
```bash
# 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
- [x] Password authentication
- [x] Persistent SSH keys
- [x] Linux service mode
- [x] Add howto gifs
- [x] Add -p flag for persistence
- [x] Windows service mode
- [x] (almost) all ssh commands supported
- [ ] MacOS service mode
## License
Licensed under either of Apache License 2.0 or MIT license at your option.