orbithub/docs/USER_GUIDE.md

Introduction

OrbitHub is a native desktop application for organizing connection profiles and launching SSH and RDP 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 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.

Getting Started

When OrbitHub opens, you land on the Profiles tab — a searchable, sortable list of every connection you've saved. Two toolbar controls in the top-right change how that list is presented:

• View: List shows every profile in one flat table; Folders groups them into the folder tree you've organized them into.
• Sort: orders the list by Name, Protocol, or Host.

Along the top of the window, a Search box filters by name, host, folder path, or tag as you type, and Protocol/Tag dropdowns narrow the list further. These filters, plus your last view mode and sort order, are remembered the next time you open OrbitHub.

Along the bottom of the Profiles tab: New, Edit, and Delete buttons for managing the selected profile. The same actions are available by right-clicking a profile or folder, and from the File menu (New Profile, New Folder).

To connect, double-click a profile, or select it and press the connect control — this opens a new tab for that session and connects automatically.

Managing Profiles

A profile stores everything needed to reach one remote host. Open New (or Edit on an existing profile) to fill in:

• 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.
• Domain — Windows domain for RDP logins (leave blank for local/ workgroup accounts or SSH 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).

Fields below Protocol change based on what you pick:

SSH: Auth Mode (Password or Private Key), and if Private Key, a Private Key file path with a Browse button, plus Known Hosts policy — see Connecting via SSH for what each policy means.

RDP: RDP Security and RDP Performance — see Connecting via RDP.

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).

Organizing Profiles

As your profile list grows, two independent tools keep it manageable:

Folders. Switch the Profiles tab to Folders view to see profiles grouped into a tree. Create a folder from the File menu or by right-clicking in the tree (New Folder), and drag any profile onto a folder to move it there. Folders can nest inside other folders.

Tags. Tags are independent of folders — a profile can be in one folder but carry several tags (e.g. prod, linux, db all at once). Use the Tag filter dropdown in the toolbar to instantly narrow the list to everything sharing a tag, regardless of which folder it's filed under.

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.

Connecting via SSH

Double-clicking an SSH profile opens a new tab with an embedded, fully interactive terminal — type directly into it as you would any terminal 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:

• 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); no password prompt unless the key itself is passphrase-protected.

Known Hosts policy. This controls how OrbitHub reacts to a server's SSH host key — the mechanism that protects against a different machine 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.
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.

Trusted host keys are recorded in your system's normal SSH known_hosts file (the same one the ssh command line tool uses), so trust decisions made through OrbitHub or a terminal ssh session carry over to each other.

Connecting via RDP

RDP sessions render in an embedded display surface inside the tab — no external RDP client window opens. Keyboard and mouse input go straight to the remote desktop while the tab has focus, and resizing the OrbitHub 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.

RDP Security controls which transport-security layer is used to negotiate the connection:

Mode	Behavior
Negotiate	Lets the client and server agree on the strongest mutually-supported option automatically. Recommended default.
NLA	Requires Network Level Authentication (credentials verified before a full session starts) — the modern standard for current Windows versions.
TLS	Requires TLS-only security, without NLA.
RDP	The legacy RDP-native security layer, for older servers that don't support TLS/NLA.

RDP Performance trades visual fidelity for responsiveness: Balanced (default), Best Quality, Best Performance, or Auto Detect (adapts based on the detected connection).

Server certificate verification. The first time you connect to an RDP host, OrbitHub trusts and remembers its TLS certificate — the same trust-on-first-use model SSH uses for host keys. If that certificate ever changes on a later connection, OrbitHub refuses the connection rather than connecting anyway, since a changed certificate can mean either a legitimate server certificate renewal or an active machine-in-the-middle presenting a different one. The event log (see below) shows the specific fingerprints involved. If the change is expected — you rotated the server's certificate yourself — reconnecting after clearing the old entry from FreeRDP's certificate store will trust the new one.

Managing Sessions

Every open connection lives in its own tab in the same window, alongside 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.

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:

• Show/Hide Events — collapse the panel when you don't need it.
• Filter — a text box to search event text, and an All / Warnings / Errors severity dropdown to narrow what's shown.
• Export Events — save the current session's full event log to a file, useful when reporting a connection problem.
• Clear Events — empty the log for that tab.

Settings & Preferences

OrbitHub remembers your preferences across restarts without any separate 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.

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 your platform. Passwords are never part of that stored data.

Troubleshooting

"Host could not be resolved" — the hostname in the profile can't be looked up by DNS. Check for typos, or try the host's IP address directly to confirm whether it's a DNS problem or something else.

SSH connection fails immediately, no prompt — double-check the profile's Port (default 22) and that a firewall or network path isn't blocking that port from your machine.

RDP: "Authentication failed. Check username and password." — confirm Username and Domain are correct for the target server; some servers require the domain to be set explicitly even for local accounts.

RDP: "RDP security negotiation failed. Try a different RDP security mode." — the server doesn't support the security mode selected in the profile. Try Negotiate first, or a more specific mode if you know what the server requires.

RDP: connection refused with a certificate-changed message — see Connecting via RDP above; this is expected, protective behavior, not a bug, whenever a previously-trusted server's certificate is replaced.

SSH: connection hangs at "Ask" waiting for host-key trust — check that policy's behavior under Connecting via SSH; switching to Accept-new avoids the prompt for genuinely new hosts while still protecting against a later key change.

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.

About & Support

OrbitHub is open source under the MIT license. Source code, issue tracking, and releases are hosted at git.darksingularity.org/DarkSingularity/orbithub.

For a list of bundled third-party libraries and their licenses, see Help → About OrbitHub inside the app.

To report a bug or request a feature, open an issue at git.darksingularity.org/DarkSingularity/orbithub/issues.