havRemote Help

Getting started

1. On first launch, use the empty connection tab. Later launches restore your previous tabs without reconnecting automatically. Press Ctrl/⌘+T whenever you need a new one.
2. In Quick Connect, choose a protocol and enter the host, port, username, and password. Enter only a host name or IP address - do not include a URL scheme, port, path, or username in the Host field. New FTP and FTPS connections entered directly in Quick Connect use passive mode. To use active mode, configure a saved site in Site Manager.
3. Select Connect. Verify any certificate or host-key prompt before accepting it.
4. Choose a local directory on the left and browse to the destination directory on the right.
5. Select files or directories, then use Upload or Download. Follow progress in the transfer area at the bottom of the window.

Tip: Use the Site Manager for private keys, SSH agent or keyboard-interactive authentication, initial directories, FTP encoding, FTP data-connection mode, and connections you use regularly.

Connections and authentication

The displayed port changes to the usual default when you select a protocol, but the server may use a different port. New, unsaved Quick Connect connections use password authentication. For the other SFTP methods, create a saved site. Reconnecting a saved-site tab with unchanged connection details keeps its saved authentication method and FTP data-connection mode.

New, unsaved FTP and FTPS connections use passive mode, which is recommended for most connections. A saved FTP or FTPS site can instead select Active. In passive mode, havRemote opens the data connection to the server. In active mode, the server connects back to your computer, so your firewall and network must allow incoming connections. By default, havRemote uses the same local address it used to connect to the server and a temporary port selected by the operating system.

Active mode local address (optional) lets you choose a different IPv4 or IPv6 address already assigned to this computer. Leave it blank for automatic selection. This can be useful with a VPN or multiple network connections, but the server must be able to reach the chosen address. havRemote uses it both to receive the incoming connection and to tell the server where to connect. It cannot listen on one address while announcing another, such as a router's public address. Do not include brackets, a port, a hostname, or URL syntax.

Choose Keyboard-interactive when the server provides all of its prompts directly. One exchange may ask for both a password and a TOTP code. Choose Password + keyboard-interactive when the server accepts the account password first and only then offers another prompt, commonly for TOTP. The initial password can be saved, but answers to keyboard-interactive prompts are used only for the current connection.

Private key reads the selected key file directly and does not use an SSH agent. SSH agent uses keys provided by a running, compatible SSH agent. If no key is accepted, havRemote does not silently switch to another agent or authentication method.

Tip: SSH agent authentication requires a running agent with your private key loaded. havRemote does not start an agent automatically.

An SFTP server host-key fingerprint identifies the server and is the value to verify in a trust prompt. A client identity fingerprint reported after agent authentication identifies the key the server accepted from you. These fingerprints represent opposite sides of the connection and normally do not match.

Saving a site

1. Open File → Site Manager or press Ctrl/⌘+S.
2. Select New site, give it a recognizable name, and choose the protocol.
3. Enter the endpoint and authentication information. You may also choose initial local and remote directories and, for FTP or FTPS, the data-connection mode and optional active-mode local-address override.
4. Select OK to save your changes, or Connect to save and connect to the selected site. Cancel discards your changes.

Use New folder to build a nested folder structure. Drag sites or folders above or below another entry to reorder them, onto the middle of a folder to move them into it, or onto blank space to move them to the root. Sites and folders can be mixed in any order. Duplicate copies a selected site or recursively copies a selected folder with all of its subfolders and sites. Saved passwords and key passphrases are not shared with any copy. Enter them separately when needed.

Sites and folders must have distinct names within the same folder (including the top level), but names can be reused in different folders. When you duplicate a folder, names inside the copy stay unchanged.

Deleting a Site Manager folder removes that folder and all of its nested saved folders and sites. The change is committed only when you save with OK or Connect. It never deletes files or directories from a remote server.

Select a site and choose Connect in the Site Manager, or open a saved site from the arrow beside its main-window button. Connect is unavailable when a folder or no entry is selected. havRemote reuses a pristine current tab when possible. Otherwise, an existing tab for the same saved site is activated and reconnected if necessary. A new tab is opened only when no matching tab is available.

Importing and exporting sites

In Site Manager, choose Export... to export the selected site, a selected folder with all its contents, or all entries to a .cson file. The current edited settings are exported without saving the Site Manager dialog. Folder structure and ordering are preserved.

Choose Import... to load a havRemote site export into the selected folder, beside a selected site, or at the top level when nothing is selected. Review the preview before importing. Existing entries are kept. Conflicting names are shown as renamed copies for your confirmation. Use OK or Connect to save the imported entries. Cancel in Site Manager discards the changes.

Exports exclude passwords, credential identifiers, trust records, key files and their local paths, local starting folders, and active-mode local-address overrides. Imported private-key sites need a local key file selected before saving or connecting. Enter other missing credentials as needed and verify server trust normally. Server names, usernames, and remote paths are still private metadata, so review a file before sharing it.

Disconnecting

During an active connection, the Connect button becomes Disconnect. Disconnecting leaves the tab and its local browser open. Transfers or externally edited files associated with the connection may require confirmation before the connection or tab can be closed.

Connection tabs

Every tab owns its connection, local browser, remote browser, and remembered directory pair. Switching tabs restores that tab's Quick Connect fields and both file views, so you do not need to navigate the local browser again for each server.

• Create a tab with the plus button or Ctrl/⌘+T.
• Close the current tab with its close button, a middle-click, or Ctrl/⌘+W.
• Drag tabs to reorder them.
• A new, empty tab starts with SFTP selected.

When havRemote starts again, it restores the open tabs in their previous order and selects the tab that was active when the application closed. Saved-site and Quick Connect identities and both browser locations are restored, but connections remain disconnected and secrets are never written into the workspace state. Reconnect each tab when you need it.

The queue and message log cover all tabs. The Connection column identifies the tab that owns each transfer. Use the Clear button beside the message-log heading to discard the currently displayed messages.

File browsers

The left browser shows local files, and the right browser shows the active server. Use the path control, Up, Refresh, or the .. entry to navigate. Press Enter after typing a path. Activating a directory opens it. Activating a regular file queues an upload or download.

• Click a column heading to sort. Click it again to reverse the direction. Drag a heading divider to resize a column. Local and remote sort choices and column widths are remembered separately, and the same layout is used in every connection tab.
• The Type column identifies regular files by their final extension, such as TXT file or GZ file for archive.tar.gz. Files without an extension, including .gitignore, remain File. Sorting by Type groups files by extension regardless of case, then by name. Folders and .. stay at the top in either direction.
• Open a selection's context menu with a secondary click, or Control-click on macOS, to access the available upload or download, editing, rename, deletion, creation, permission, and refresh actions. On Windows and Linux, you can also use the context-menu key or Shift+F10.
• Drag selected local items to the remote list to upload them, or selected remote items to the local list to download them. These in-app drops work between the two lists in the same connection tab and use the currently displayed destination directory. You can also drop files or directories from your file manager onto a connected remote list to upload them.
• The remote list can show permissions and owner/group data when the server reports them. An empty value usually means that the protocol or server did not supply it.
• Symlinks are shown as links but are never followed during recursive transfers.
• Use Refresh when another program or server-side process may have changed the directory. havRemote also refreshes a visible local destination after a download and a visible remote destination after an upload.

Transfers, conflicts, and resume

Starting a transfer

Select one or more local items and choose Upload, or select remote items and choose Download. Directories are enumerated and transferred recursively. Files from different connection tabs share the same queue and the configured limit on simultaneous transfers.

Queue views and actions

The context menu offers the same actions as the buttons, with the same availability, plus Copy all.

• Queue contains waiting, enumerating, running, and paused work.
• Failed contains transfers that ended with an error or were canceled.
• Completed contains successfully finished work.
• Pause, Cancel, and Retry require exactly one selected transfer that supports the action. They are disabled when multiple entries are selected.
• Remove requires exactly one selected completed, failed, or canceled entry and deletes it from the queue records. Removing a failed transfer asks for confirmation because it discards that transfer's retry and recovery information.
• Clear removes every entry in the current Failed or Completed view. Clearing failed transfers gives the same warning. Partial local and temporary remote files are left in place for safety.
• Copy copies selected entries in any of the three views. Use the Copy button, the context-menu action, or Ctrl/⌘+C while the transfer list has focus. Select multiple entries with Ctrl/⌘ or Shift, or press Ctrl/⌘+A to select every entry in the focused list.
• Copy all in the context menu copies the entire current view. Copy is enabled only with a selection. Copy all is enabled whenever the view is not empty.

Copied transfers are tab-separated plain text with localized column headers, every displayed column, and full error details. Copying does not requeue transfers or change their state.

Use Export... → Export selected... or Export all... on the button row or context menu to save a .csv report from any transfer view. The report captures the rows before the save dialog opens, with translated headings, the current column order, and full error details. Selection export requires selected rows. Whole-view export requires a nonempty view. Reports do not change transfers and cannot be imported to restore a queue. Only entries still present in the view can be exported.

CSV reports use UTF-8 and comma-separated quoted fields. When opening one in a spreadsheet, choose UTF-8 and comma as the delimiter if needed. Secrets and control characters are sanitized, and formula-like text is prefixed with an apostrophe. Existing files require overwrite confirmation. Application configuration, transfer recovery, and trusted-host files cannot be replaced by an export.

The Speed and ETA columns show a live average for running file transfers. ETA is available only when the total size is known. Paused, waiting, terminal, and directory-enumeration entries leave these fields blank.

Failed uploads and downloads add an Error entry to the message log and show an error dialog with the connection, transfer direction, remote path, and error. Failures that occur close together are grouped in one notification. The transfers remain in Failed. After resolving the problem, select an entry and choose Retry. Pausing or canceling a transfer does not trigger this error reporting, and failures restored when starting havRemote do not trigger it again.

FTP/FTPS uploads report insufficient storage or an exceeded quota when the server supplies that reason. If the connection fails before a final reply is available, havRemote may only be able to report an interrupted connection. Ask the server administrator to check the server logs if the cause is unclear. Partial uploads are kept so you can retry or resume safely after resolving the problem.

A server may have completed a final operation even when the reply was lost. havRemote does not silently repeat destructive work with an uncertain outcome. Inspect the destination before confirming a retry.

Destination conflicts

With Ask, the initial default policy, havRemote offers the choices that are safe for that transfer:

• Overwrite replaces the destination.
• Skip leaves the destination unchanged.
• Rename transfers the incoming item under another name.
• Resume continues a verified partial transfer.

You may apply a choice to remaining queue conflicts. A safety-sensitive conflict, such as a remote file changing during external editing, is always handled individually.

When you rename an incoming file, havRemote remembers the chosen destination for retries, including after restarting the application. For directory transfers, it remembers each file's chosen name separately. Resume information stays attached to that destination. Choosing a new name does not reuse a checkpoint for the old one.

Partial files and safe resume

Downloads use a sibling file ending in .havremote.part. Uploads use a temporary remote name when the server supports it. Resume is offered only when recorded source and destination metadata still matches. Otherwise, start again or choose another conflict action.

Resuming FTP and FTPS uploads requires server support. If the server does not support it, restart the upload from the beginning or ask the server administrator to enable upload resume.

File operations and permissions

Local files

• New folder creates a directory in the current location.
• Edit opens one selected file with the configured external editor.
• Rename edits the selected item's name.
• Delete moves selected items to your system's Trash or Recycle Bin where possible. Items that cannot be moved there may be permanently deleted.

Remote files

• Create an empty file or a directory in the current remote location.
• Rename files and directories.
• Open a regular file for external editing.
• Change the permission mode of one or more supported items.
• Permanently delete selected items. Remote directories are deleted recursively.

Warning: Remote deletion is permanent and cannot be undone by havRemote. Read the confirmation carefully, especially for directories or multiple selections.

With either file list focused, press Delete without modifier keys to delete one or more selected items using the same confirmation as the button. Remote items are permanently deleted. Local items go to your system's Trash or Recycle Bin where possible. Otherwise they may be permanently deleted. This shortcut does not delete files while you are typing a path or editing a filename. Shift+Delete does not bypass confirmation or change the local deletion behavior.

Changing remote permissions

Select one or more remote files or directories and choose Permissions. Set owner, group, and other read/write/execute bits, optional setuid/setgid/sticky bits, or enter an exact three- or four-digit octal mode such as 0755. Availability depends on the server. havRemote will not change permissions on the remote root, symlinks, or special files.

External editing

Open Settings to choose the system default application or a custom editor. A custom argument template must contain {file} exactly once. havRemote inserts the selected file path as one literal argument without using a command shell.

Local files

Select one local file and choose Edit. If its file type is blocked when using the system-default application, select a trusted custom editor to open it as data.

Remote files

havRemote downloads a private working copy, opens it in the editor, watches for stable saves, and uploads changes through the normal transfer queue. Before replacing the server copy, it checks that the remote file has not changed since you opened it. If it has changed, havRemote asks before overwriting the newer revision.

Keep havRemote running: Leave the connection and tab open while editing. If monitoring, verification, disconnection, or shutdown prevents a safe upload, havRemote keeps the local recovery copy and reports its location.

Settings and history

Appearance and language

In Settings, you can choose a light or dark theme and select from the available languages. Language changes apply immediately. A theme change takes effect after restarting havRemote.

Open Help → View Help or press F1 to read the help in the selected application language. If no matching help page is installed, havRemote opens the English help instead.

Transfers and connections

Simultaneous transfers limits the number of file transfers running across all connection tabs and takes effect after a restart. The connection timeout limits how long a new server connection may take. The idle timeout limits how long a command may make no network progress. Timeout changes apply when a tab reconnects.

FTP/FTPS file uploads and downloads have a separate low-speed timeout: the transfer fails if measured throughput stays below 1 byte/sec for 30 seconds. This applies to passive and active mode, including explicit and implicit FTPS. It is not a limit on total transfer duration. Brief stalls are allowed. A timeout keeps partial files for safe resume and does not automatically retry. The idle-timeout setting still applies to FTP command responses and SFTP operations.

The default conflict action can be Ask, Overwrite, Skip, Rename incoming item, or Resume when safe. A change applies immediately to newly queued transfers. Existing queue entries keep the policy with which they were created.

After saving a theme or simultaneous-transfer change, havRemote offers to restart immediately. Decline to apply those changes on your next launch instead. The prompt warns about unfinished transfers and files open in external editors: interrupted transfers return paused when recovered, and restarting stops monitoring edited files, so later editor saves are no longer uploaded automatically.

Quick Connect history

After a successful unsaved Quick Connect, havRemote remembers up to 20 recent endpoints. Select the History button to reuse an endpoint or clear the entire list. History stores the protocol, host, port, and username only - never the password. Clearing it also removes remembered directory pairs for those recent endpoints.

Remembered workspace

havRemote remembers open tabs and their order, the selected tab, local and remote directories for saved sites and recent endpoints, local and remote list sorting and column widths, and the main window's size, position, and maximized state. Choose Settings → Main window → Restore default size, then click OK to apply and save the default dimensions. Cancel leaves the window placement unchanged. When a saved site is opened, its remembered directory pair is restored first. Its configured initial directories are used only when no remembered pair exists.

Transfer recovery

Unfinished and failed transfers are stored separately in queue.cson (see data locations). After a restart, interrupted work appears paused in a recovered connection tab. Select that tab, reconnect to the same site and exact endpoint, then choose Retry. Completed and canceled transfers are not kept as permanent history. The queue file contains paths, endpoint identity, progress, errors, and safe-resume metadata, but no passwords or key passphrases.

If the queue file cannot be loaded: havRemote reports the error and leaves the file unchanged. Transfers remain usable, but queue persistence is disabled for that session, so new queue changes will not survive a restart. Close havRemote, back up queue.cson, then correct it or move it aside and restart to enable recovery persistence again. havRemote does not reset an invalid queue automatically.

Updates

Select Help → Check for Updates to query the latest published havRemote release that GitHub does not mark as a prerelease. A manual check runs even when automatic checks are disabled or the offered version was previously skipped.

Automatically check once per day is enabled by default. At startup, havRemote checks only when no attempt has completed in the past 24 hours. Choosing Skip this version suppresses automatic notices only for that exact version. A newer release is still shown, and a manual check still shows the skipped version.

Release notes are displayed as plain, read-only text. Download opens the download link in your default browser. View release opens the release's GitHub page. havRemote does not install updates or replace program files.

Privacy: Update checks use the project's public GitHub Releases API over HTTPS. No GitHub account, access token, or repository secret is used. GitHub receives the ordinary connection metadata of an HTTPS request, such as the public IP address.

Security

• Prefer SFTP or FTPS. Plain FTP sends credentials and file contents without encryption and always produces a warning.
• Verify trust prompts. Compare SFTP host-key fingerprints or FTPS certificate information with a value obtained through a separate trusted channel.
• FTPS validation checks that the server certificate is trusted and matches the hostname. A saved exception remembers the certificate's public key for that host and port only. An exception is allowed only for a currently valid self-signed certificate whose sole problem is a missing trusted issuer. It does not bypass expiry, detected revocation, hostname mismatches, or other certificate-validation failures.
• SFTP trust is keyed by host and port. Unknown keys may be accepted once or stored permanently. A changed key is blocked until you explicitly replace it.
• Secrets such as passwords and private-key passphrases are never stored in the settings file or Quick Connect history. Saved secrets are kept in the operating system's credential store.
• Interactive answers such as TOTP codes are kept only for the current authentication exchange and are never saved.
• Diagnostics are sanitized before display. Still review paths and server messages before sharing a screenshot or log excerpt.
• Path safety rejects paths that escape the chosen destination and unsafe or conflicting filenames.

Keyboard shortcuts

Throughout this help, Ctrl/⌘ means Ctrl on Windows and Linux, or the Command key ⌘ on macOS. The application menus also show their shortcuts.

Delete means forward delete, not Backspace. On compact Mac keyboards, use Fn+Delete. Depending on your keyboard settings, F1 may also require Fn. If a shortcut is unavailable, use the corresponding button or menu action.

Configuration files and data locations

Settings and recovery data are stored for your user account. The configuration and local application-data folders depend on your operating system.

Configuration error messages include the affected file's path. When havRemote keeps a remote-edit recovery copy, its message also shows where that file was saved.

Close havRemote before editing its settings file by hand. Your comments are preserved when havRemote saves changes.

Do not discard a reported configuration error blindly. havRemote does not overwrite malformed or unsupported configuration. Correct or preserve and remove the file, then restart the application.

Changelog

Version 0.1.0 - 2026-09-17

• First Release

Troubleshooting