sshui 0.2.0

A rust lib to make a customizable user-interface over SSH with Ratatui
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# SSHUI

A Rust framework for building interactive terminal user interfaces (TUIs) that run over SSH. Built on top of [Ratatui](https://github.com/ratatui-org/ratatui) and [russh](https://github.com/Eugeny/russh).

## Demo


https://github.com/user-attachments/assets/f3a5bf04-11df-4d3f-a8c0-1e2e67021fa4


## Features

- **SSH Server** - Host your TUI application on an SSH server
- **Ratatui Integration** - Build beautiful terminal UIs using the Ratatui framework
- **Client Isolation** - Each SSH client gets its own application instance
- **ANSI Rendering** - Full support for colors and styles
- **Terminal Resizing** - Handles dynamic terminal size changes
- **Customizable Auth** - Ask for a specific username and password (or not!)
- **Backend Support** - Write your own backend to connect clients to each other!

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
sshui = "0.2"
ratatui = "0.28"
anyhow = "1.0"
```

## Quick Start

Implement the `App` trait for your TUI:

```rust
use sshui::{App, SSHUITerminal, InputEvent, KeyCode, KeyEvent};
use anyhow::Result;

struct MyApp {
    counter: i32,
    exit: bool,
}

impl App for MyApp {
    fn render(&mut self, terminal: &mut SSHUITerminal) -> Result<Option<String>> {
        terminal.draw(|frame| {
            let area = frame.area();
            // Draw your UI here
        })?;

        Ok(if self.exit {
            Some("Exited".to_string())
        } else {
            None
        })
    }

    fn input(&mut self, event: InputEvent) {
        if let InputEvent::Key(KeyEvent { key, .. }) = event {
            match key {
                KeyCode::Char('q') => self.exit = true,
                KeyCode::Up => self.counter += 1,
                KeyCode::Down => self.counter -= 1,
                _ => {}
            }
        }
    }
}

impl Default for MyApp {
    fn default() -> Self {
        Self {
            counter: 0,
            exit: false,
        }
    }
}
```

Start the SSH server:

```rust
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = sshui::Config::default();
    // also include ssh keys
    // which you can get using the keyring feature
    // and the sshui::get_ssh_key function

    sshui::new_server(config, ("0.0.0.0", 2222), || Box::new(MyApp::default()))
        .await?;

    Ok(())
}
```

Connect via SSH:

```bash
ssh -p 2222 localhost
```

Press `Ctrl+C` to exit.

## Examples

The repository includes example applications:

- **Example** - All the following examples at once :)
- **Graph** - A really cool grapher in the terminal (holy moly)
- **Counter** - A simple incrementing counter with keyboard controls
- **Wordle** - A word guessing game
- **Login** - A 'Hello World' behind the username 'hello' and password 'world'

Run an example: (you can specify the port with --port {number})

```bash
cargo run -p example --release
```

Then connect via SSH:

```bash
ssh -p 2222 localhost
```

## Limitations

- Cursor position cannot be queried from SSH clients, so `get_cursor()` always returns (0, 0)
- Password authentication is disabled by default (implement `auth_password()` if needed)
- Pixel dimensions are not available over SSH

## License

© Kodeur_Kubik - Code available under the MIT License