dosh/docs/PUBLIC_READINESS.md

Dosh Public Readiness

Dosh's defensible public claim is fast terminal attach and reconnect. It should not claim full Mosh replacement status until the feature matrix below is green and the comparison benchmark is reproducible outside the author's homelab.

Objective Benchmarks

Run the same-host SSH comparison:

make bench-docker-ssh

Run the Dosh, SSH, and Mosh comparison:

make bench-docker-mosh

The Mosh-inclusive target builds one Docker image with OpenSSH, Mosh, dosh-server, and dosh-auth. It uses the same generated key, localhost network path, SSH server, and container for all samples.

Reported metrics:

Metric	Meaning
ssh_true_ms	Time to run ssh host true with the same key/options.
dosh_attach_ms	Time for dosh-client --attach-only to render the first frame and detach on the configured path. With --no-cache, this is cold SSH bootstrap plus UDP attach.
dosh_cached_attach_ms	Time for a warmed Dosh client to attach using cached UDP credentials/tickets, render the first frame, and detach. This is the fast-path claim and should be approximately network RTT plus local process/render overhead.
mosh_start_true_ms	Time for mosh host -- true to bootstrap, run true, and exit.

These are not identical workloads. They are still useful because they measure the startup path each tool must pay before useful remote work begins. Public numbers must include the command, machine, OS, CPU, network path, and sample count.

Do not cite cold dosh_attach_ms as the core speed claim. Cold Dosh still pays SSH startup/authentication. Cite dosh_cached_attach_ms for repeat attach/reconnect speed, and cite cold dosh_attach_ms only to show that fallback remains competitive with ordinary SSH.

Feature Matrix

Feature	Mosh	Dosh now	Public status
SSH-based first authentication	yes	yes	ready
Encrypted UDP terminal data	yes	yes	ready
Roaming by client address change	yes	yes	needs more hostile-network tests
Survive sleep or network loss	yes	yes	needs long-running soak tests
Fast repeat attach without SSH	no	yes, via attach tickets	core differentiator
Resident server daemon	no	yes	core differentiator
One UDP port for all sessions	port range by default	yes	ready
Fresh session by default	yes	yes	ready
Named persistent sessions	no built-in shared session model	yes	ready
Multiple clients on one session	no	yes	needs conflict-policy docs
View-only clients	no	yes	ready
Full-screen TUI correctness	yes	improving	must stay green before public push
Predictive local echo	mature	guarded printable-only opt-in	not parity
Non-destructive disconnect UI	yes	not currently	needed
Unicode edge-case handling	strong	basic terminal emulator dependent	not parity
X11 forwarding	no	no	non-goal unless tunneled separately
SSH agent forwarding	no	no	planned as forwarding channel
Local TCP forwarding, -L	no	not implemented	planned
Remote TCP forwarding, -R	no	not implemented	planned
Dynamic SOCKS forwarding, -D	no	not implemented	later

SSH Config Inheritance

Dosh intentionally delegates SSH parsing and authentication to OpenSSH. Bootstrap uses the user's normal ssh command, so ~/.ssh/config options such as Host, HostName, User, Port, IdentityFile, ProxyJump, and UserKnownHostsFile continue to apply.

Dosh also calls ssh -G <alias> to infer the UDP target host when no dosh_host is configured. To write explicit Dosh host entries from SSH aliases:

dosh import-ssh palav homelab

This appends entries to ~/.config/dosh/hosts.toml without trying to become an OpenSSH config parser.

Forwarding Plan

SSH forwarding cannot be copied by keeping the bootstrap SSH connection open, because that would remove Dosh's fast reconnect advantage and would break after roaming. Dosh forwarding needs native encrypted channels over the Dosh transport.

Minimum viable forwarding design:

CLI	Meaning
dosh -L 8080:127.0.0.1:80 host	Local listener on the client; server connects to target.
dosh -R 8080:127.0.0.1:80 host	Remote listener on the server; client connects to target.

Protocol work required:

• Add stream-open, stream-data, stream-ack, and stream-close packet types.
• Use per-stream flow control separate from terminal frame ordering.
• Never let bulk forwarding traffic delay terminal input/output packets.
• Bind forwarding permissions to the same SSH-authenticated user as the terminal.
• Add tests with dropped/reordered UDP packets.

This is a publishable differentiator once implemented, but it should not be claimed until it exists.

Before Public Launch

• Keep cargo test, make bench-docker-ssh, and make bench-docker-mosh green.
• Add a non-destructive disconnect indicator.
• Run scripted TUI tests for alternate-screen apps, arrow keys, resize, mouse mode, bracketed paste, and terminal cleanup.
• Publish benchmark output with raw samples, not just averages.
• Mark prediction as experimental until it has a real framebuffer model.