koh

A Rust, peer-to-peer remote shell inspired by mosh, built on iroh / QUIC.

koh gives you a responsive remote shell that survives network changes, suspend/resume, and reconnects — without SSH, open ports, or server-side accounts.

Install and usage

cargo install koh

koh authorizes by endpoint id. There are no passwords or accounts.

# On the client, print its id:
koh id

# On the server, allow that client and start a shell host:
koh serve --allow <client-id>

# On the client, connect to the server:
koh connect <server-id>

Useful commands:

koh id                    # print this machine's endpoint id
koh serve --allow <id>    # host a shell for an allowed client
koh connect <id>          # connect to a server id
koh key passwd            # change the identity-key passphrase
koh key info              # show identity-key information

Useful flags:

--clipboard               # opt in to OSC-52 clipboard writes
--shell <program>         # host a program instead of the login shell (repeat to pass args)
--key-file <path>         # use a custom identity-key path
--session-ttl-secs <n>    # keep detached sessions around longer/shorter
--max-connections <n>     # limit concurrent connections
--max-sessions <n>        # limit sessions

Keys live under ~/.config/koh/ by default.

Platforms: Linux, macOS, and Android via Termux. Windows is not supported; use WSL2.

Android / Termux install

1. Install Termux from the Termux GitHub releases. Do not use the old Play Store build.

2. In Termux, install Rust and build tools:

   pkg update
   pkg install rust clang pkg-config
   

3. Install koh:

   cargo install koh
   

If DNS resolution is broken on your Android device, try setting an explicit resolver:

KOH_DNS=1.1.1.1 koh connect <server-id>

As a library

koh's server and client are callable from another binary. Depend on it without the cli feature (clap stays out of your tree) and pick exactly one backend-* terminal feature:

[dependencies]
koh = { version = "0.10", default-features = false, features = ["backend-termina"] }

The stable surface is the four config types and their entry points: koh::server::{serve, ServeConfig}, koh::client::{connect, ConnectConfig, run_id, IdConfig} and koh::keycmd::{run, KeyConfig}. ServeConfig::command is an argv, so any program can be hosted, not only a shell:

use koh::server::{serve, ServeConfig};

serve(ServeConfig {
    allow: vec![client_id],
    command: vec!["zellij".into(), "attach".into(), "-c".into(), "main".into()],
    ..Default::default()
})
.await?;

The koh binary is the same code behind clap; cargo install koh is unaffected.

Highlights

• Built in Rust on iroh peer-to-peer QUIC; connects by endpoint id instead of hostname/port.
• Mosh-style predictive local echo and screen-state sync for responsive shells on bad networks.
• Detachable sessions survive suspend/resume, IP changes, and reconnects without tmux.
• No SSH bootstrap, no listening port, and no port forwarding needed.
• Not wire-compatible with mosh or SSH; koh is its own protocol/tool.
• Intended for personal machines you control; not a full SSH replacement.
• Does not provide multi-user accounts, file transfer, scrollback sync, or Windows support.

Status

koh is experimental and intended for personal use on machines you control.

See docs/THREAT_MODEL.md for the security model, SECURITY.md for vulnerability reporting, and docs/ARCHITECTURE.md for implementation details.

License

MIT, from 0.10.0 onward. Releases before 0.10.0 remain available under GPL-3.0-or-later.