DarkSingularity/orbithub
Internal
Public Access
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 8 Wiki Activity

Update README and in-app User Guide for VNC, Import/Export, and connect-time prompting

Browse Source 
Both docs still described VNC as unimplemented and required usernames
up front for SSH/RDP -- neither has been true for a while. Brings them
in line with the actual current feature set: VNC's encodings/clipboard/
cursor sync/display modes and honest Apple Screen Sharing auth status,
blank-username connect-time prompting across all three protocols,
profile Import/Export and mRemoteNG import, and the new prompt
visibility behavior (issue #22). docs/USER_GUIDE.md also drives the
in-app Help -> User Guide dialog and the PDF shipped with releases.

Bump version to v2026.9.16.7.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ksmith
2026-09-16 11:20:18 -06:00
co-authored by Claude Sonnet 5
parent 1506d87719
commit 34c16cbfa8
3 changed files with 171 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/USER_GUIDE.md
+113 -15
View File
@@ -1,16 +1,19 @@
## Introduction
OrbitHub is a native desktop application for organizing connection profiles
and launching SSH and RDP sessions from one place, in a single tabbed
and launching SSH, RDP, and VNC sessions from one place, in a single tabbed
window. It runs on Windows, Linux, and macOS.
This guide covers everyday use: creating and organizing profiles,
connecting over SSH and RDP, managing active sessions, and what to do when
something goes wrong. It does not cover installation or building from
connecting over SSH, RDP, and VNC, managing active sessions, and what to do
when something goes wrong. It does not cover installation or building from
source — see the project's `README.md` and `docs/BUILDING.md` for that.
VNC support is planned but not yet implemented; profiles can be tagged for
it, but connecting will show an "unsupported protocol" message for now.
VNC support covers standard VNC Authentication and no-auth servers
(TigerVNC, x11vnc, TightVNC, and similar). macOS's built-in Screen Sharing
server uses two undocumented, reverse-engineered authentication schemes
that are implemented but not yet confirmed working end to end against a
real macOS server — see [Connecting via VNC](#connecting-via-vnc).
## Getting Started
@@ -43,15 +46,19 @@ A profile stores everything needed to reach one remote host. Open **New**
- **Name** — a label for the profile; shown on its tab and in the list.
- **Host** — hostname or IP address.
- **Port** — defaults to `22` for SSH, `3389` for RDP.
- **Username** — the account to log in as.
- **Port** — defaults to `22` for SSH, `3389` for RDP, `5900` for VNC.
- **Username** — the account to log in as. Optional for every protocol —
leave it blank and OrbitHub asks for one inline the first time you
connect that profile, the same way it already asks for a password. (VNC
servers mostly ignore username entirely; macOS Screen Sharing is the
exception and requires one — see
[Connecting via VNC](#connecting-via-vnc).)
- **Domain** — Windows domain for RDP logins (leave blank for local/
workgroup accounts or SSH profiles).
workgroup accounts, SSH, or VNC profiles).
- **Tags** — free-form, comma-separated labels for filtering and grouping
(e.g. `prod, linux, db`).
- **Folder** — where the profile lives in the Folders view.
- **Protocol** — `SSH`, `RDP`, or `VNC` (VNC is accepted but not yet
connectable — see Introduction).
- **Protocol** — `SSH`, `RDP`, or `VNC`.
Fields below Protocol change based on what you pick:
@@ -63,6 +70,9 @@ policy means.
**RDP**: **RDP Security** and **RDP Performance** — see
[Connecting via RDP](#connecting-via-rdp).
**VNC** has no protocol-specific fields beyond Host/Port/Username above —
see [Connecting via VNC](#connecting-via-vnc).
Passwords are never saved in the profile — OrbitHub asks for them each
time you connect (unless you've set up private-key SSH auth, which needs
no password to be entered per-connection if the key itself has none).
@@ -85,6 +95,24 @@ Combine both with the **Search** box (matches name, host, folder path, or
tags) and the **Sort** control (Name / Protocol / Host) to find what you
need quickly even with a large profile list.
## Importing and Exporting Profiles
The **File** menu has three options for moving profiles in or out of
OrbitHub:
- **Export Profiles...** — saves your entire profile list, including
folder structure and tags, to a JSON file. Passwords are never included,
since OrbitHub never stores them in the first place.
- **Import Profiles...** — reads that same JSON format back in, recreating
folders and profiles. Existing profiles aren't touched; entries missing
a name or host are skipped and reported in the summary.
- **Import from mRemoteNG...** — reads an mRemoteNG connections `.xml`
file and creates equivalent OrbitHub profiles. Passwords are never
imported — you'll be prompted the first time you connect each imported
profile, same as a new one. Connections using a protocol OrbitHub
doesn't support are skipped and listed in the import summary. This is a
one-way conversion; there's no export back to mRemoteNG's format.
## Connecting via SSH
Double-clicking an SSH profile opens a new tab with an embedded, fully
@@ -93,6 +121,8 @@ emulator. A **theme** selector lets you switch between `Dark`, `Light`,
and `Solarized Dark`; your choice is remembered for future sessions.
**Authentication.** Set in the profile itself:
- **Username** — if left blank in the profile, OrbitHub asks for one
inline the first time you connect, right alongside the password prompt.
- **Password** — OrbitHub prompts for a password each time you connect.
It is never stored.
- **Private Key** — point at a key file (via the profile's Browse button);
@@ -105,7 +135,7 @@ silently impersonating a host you've connected to before:
| Policy | Behavior |
|---|---|
| `Ask` | Prompts you to confirm trust the first time a host is seen, and on any later change. Recommended default. |
| `Accept-new` | Silently trusts a host the first time it's seen, but still stops and warns if a previously-trusted host's key later changes. |
| `Accept New` | Silently trusts a host the first time it's seen, but still stops and warns if a previously-trusted host's key later changes. |
| `Strict` | Never trusts an unknown host automatically — the connection fails until you've manually confirmed the host key some other way. |
| `Ignore` | Skips host-key checking entirely. Only use this for throwaway/test environments — it removes protection against on-path attacks. |
@@ -123,7 +153,8 @@ window renegotiates the remote resolution to match. Clipboard content
syncs between your machine and the remote session automatically.
**Authentication** uses the profile's Username/Domain fields; OrbitHub
prompts for the password at connect time.
prompts for the password at connect time, and for a username too if the
profile's own Username field was left blank.
**RDP Security** controls which transport-security layer is used to
negotiate the connection:
@@ -151,6 +182,51 @@ expected — you rotated the server's certificate yourself — reconnecting
after clearing the old entry from FreeRDP's certificate store will trust
the new one.
## Connecting via VNC
VNC sessions render in an embedded display surface inside the tab, like
RDP — no external VNC client window opens.
**Authentication.** VNC servers don't have a fixed username/password
convention the way SSH and RDP do, so OrbitHub always prompts for a
password at connect time (leave it blank if the server doesn't require
one — no-auth servers exist and are supported). Most VNC servers ignore
username entirely; the one common exception is **macOS's built-in Screen
Sharing**, which does require one — see the Apple Screen Sharing note
below if you're connecting to a Mac.
**Display mode.** Right-click a VNC session's tab to choose:
- **Scale to Fit** (default) — the whole remote screen is scaled to fit
the tab, like RDP.
- **Actual Size (Scrollbars)** — renders at the remote's native pixel
size, with scrollbars for panning. Useful when scaling would make small
text illegible.
Your choice is remembered across sessions. Unlike RDP, VNC has no way to
renegotiate the remote screen's resolution to match your window size —
resizing the OrbitHub window changes how much of a scaled-down remote
screen you can see, not the remote resolution itself.
**Clipboard and cursor.** Clipboard content syncs between your machine and
the remote session in both directions, and the remote's cursor shape (not
just position) is mirrored locally when the server supports it.
**Encodings.** OrbitHub negotiates whichever of Raw, CopyRect, Hextile,
ZRLE, or Tight the server prefers — this is automatic and requires no
configuration; more efficient encodings (Tight, ZRLE) simply mean better
performance over slower links.
**Apple Screen Sharing (macOS).** macOS's built-in Screen Sharing server
doesn't use a standard, documented VNC authentication method — it uses two
undocumented schemes that OrbitHub implements based on reverse-engineering
work, but neither is yet confirmed to authenticate successfully against a
real macOS server. If you're connecting to a Mac's Screen Sharing and see
an authentication failure, this is the likely cause rather than a wrong
username or password; check
[docs/PROGRESS.md](https://git.darksingularity.org/DarkSingularity/orbithub/blob/main/docs/PROGRESS.md)
(Milestone 6) for the current status, or a VNC server you install yourself
on the Mac (e.g. TigerVNC) as a workaround in the meantime.
## Managing Sessions
Every open connection lives in its own tab in the same window, alongside
@@ -158,6 +234,14 @@ the Profiles tab. A tab's title and a colored state indicator show
whether it's connecting, connected, disconnected, or failed. Closing a
tab disconnects that session; opening a profile again starts a fresh one.
**When OrbitHub needs a username or password from you**, the tab shows a
highlighted prompt bar with a Connect/Cancel pair — this happens for a
blank-username SSH/RDP profile, any RDP or SSH password prompt, and any
VNC connection (VNC always asks for a password, even if blank). If that
prompt appears on a tab you're not currently viewing, the tab's title
gets a `(Needs input)` suffix and its color changes so it's easy to spot
among several open sessions.
Each session tab includes a collapsible **event log** beneath the
connection surface — a timestamped record of connection state changes,
warnings, and errors for that session. Controls above the log let you:
@@ -176,8 +260,9 @@ settings screen — they're saved automatically as you use the app:
- Profile list: search text, view mode (List/Folders), Protocol/Tag
filters, and sort order.
- Session tabs: terminal theme choice, and whether the events panel is
shown or hidden for new tabs.
- Session tabs: terminal theme choice, whether the events panel is shown
or hidden for new tabs, and VNC display mode (Scale to Fit / Actual
Size).
Profile data itself (names, hosts, tags, folder structure, and so on) is
stored in a local SQLite database — see the README for its exact path on
@@ -209,10 +294,23 @@ certificate is replaced.
**SSH: connection hangs at "Ask" waiting for host-key trust** — check
that policy's behavior under
[Connecting via SSH](#connecting-via-ssh); switching to `Accept-new` avoids
[Connecting via SSH](#connecting-via-ssh); switching to `Accept New` avoids
the prompt for genuinely new hosts while still protecting against a later
key change.
**VNC: "Authentication or authorization failure"** — for most VNC
servers this means a wrong password. If you're connecting to **macOS
Screen Sharing** specifically, this is the expected result right now — see
the Apple Screen Sharing note under
[Connecting via VNC](#connecting-via-vnc).
**VNC: connection closes immediately with no prompt** — some servers
(including macOS Screen Sharing in some configurations) close the
connection outright rather than negotiating; confirm the server is
actually running and reachable on the profile's port (default `5900`),
and that no allowlist on the server side is blocking your account or
machine.
If none of this covers what you're seeing, a session's exported event log
(see Managing Sessions) is the most useful thing to include when asking
for help or filing an issue.