Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

ssh-obi cannot find ssh

Install OpenSSH client tools and make sure ssh is on PATH. ssh-obi uses the system ssh binary and does not include its own SSH implementation.

Remote install reports unsupported target

The Unix bootstrap chooses a tarball from uname -s and uname -m. If it prints an unsupported target error, no release tarball is currently published for that OS/CPU pair.

Use Platform Support to check the published target list.

If the platform can build Rust code, install the server on the remote account instead:

cargo install --features server-bin ssh-obi

The bootstrap probes ~/.cargo/bin/ssh-obi-server directly and also accepts a compatible ssh-obi-server on PATH, so Cargo-installed and distro-packaged servers can be used without a prebuilt tarball.

Windows install succeeds but ssh-obi.exe is not found

The Windows bootstrap updates the user’s PATH. Existing terminals may not see that change.

Open a new terminal and try:

ssh-obi.exe --help

Arrow keys do not work from Windows

Use Windows Terminal or another console with Windows virtual terminal input support. While attached, ssh-obi.exe enables that mode so special keys are sent to the remote PTY as escape sequences.

To check whether key bytes are reaching the remote shell, run:

cat -v

Then press Up. A working Windows client should print something like ^[[A. Press Ctrl-C to leave cat.

The picker shows (unknown) in WHAT

The WHAT column is best-effort. It depends on the remote OS and process table details. Failure to detect the foreground command does not affect session correctness.

ssh-obi deliberately avoids wrapping or instrumenting your shell to improve this field.

Output repeats after reconnect

This is expected. Reattach replays the session’s current bounded buffer before live forwarding resumes. ssh-obi does not maintain a per-client replay cursor.

Old output is missing after reconnect

The session replay buffer is bounded. Old output belongs in the local terminal scrollback.

Typing feels softer than plain SSH

ssh-obi is designed to stay close to plain SSH, but the interactive path is not byte-for-byte identical to an OpenSSH client attached directly to a remote PTY.

Input travels through the local ssh-obi client, the system ssh process, the remote broker, a Unix-domain socket, and the per-session daemon before it reaches the remote PTY. Output returns through the same layers in reverse. Each layer flushes promptly, and there is no intentional long sleep in the hot path.

On Unix clients, ssh-obi does intentionally coalesce immediately pending stdin bytes for a very short window before framing and sending them. This keeps paste and bursty input from becoming one protocol frame per byte, but it can add up to about 2 ms before an isolated keystroke is sent. That small batching window, plus normal SSH, network, scheduler, and terminal latency, can feel a little softer than direct SSH on very low-latency links.

This behavior is a latency/throughput tradeoff, not a correctness issue. It does not change the bytes the remote shell receives, introduce in-band escape commands, or change reconnect/replay semantics.

Reconnect eventually gives up

Automatic reconnect uses capped exponential backoff: 125ms, 250ms, 500ms, 1s, then 2s for later attempts. After 10 failed reconnect attempts, ssh-obi reports failure instead of retrying forever.

A session is busy

A session can have only one attached client. If another client is already attached, a second attach attempt gets SessionBusy.

During automatic reconnect, ssh-obi treats SessionBusy specially only for the exact session it is trying to recover: it asks the stale attached client to detach and then retries. Manual attaches still leave the busy session alone.

Use:

ssh-obi --list user@example.com

to inspect sessions, or:

ssh-obi --detach --session ID user@example.com

to ask the session to detach the attached client for a known session.

MOTD is shown when a session starts

New sessions print the remote host MOTD before the shell starts. This includes readable non-empty /run/motd.dynamic and /etc/motd files, plus readable non-empty files in /etc/motd.d/.

To suppress this output for the remote account, create:

touch ~/.hushlogin

A deliberate detach reconnects unexpectedly

Use the in-session helper:

ssh-obi-server --detach

This asks the remote session to detach and causes the client to exit gracefully. Simply closing the terminal, killing SSH, or losing the network is ambiguous, so the client reconnects.

PowerShell bootstrap cannot run

Use a command that bypasses the current process policy:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://obi.menhera.org/bootstrap.ps1 | iex"

If that is blocked by local policy, download the script and inspect it before running it in an allowed shell.