Remote Machines

Borg UI uses a system SSH key for remote machine access.

Use Remote Machines to:

• connect to NAS or Linux servers
• deploy the Borg UI public key
• test SSH access
• use remote paths in repositories and backup sources

The old /ssh-keys route redirects to Remote Machines.

Key Model

Borg UI stores one system SSH key and uses it for remote connections.

Supported key types:

• ED25519, recommended
• RSA, for older systems
• ECDSA, for compatibility

Generate the key in the UI unless you have a reason to import an existing key.

Add a Remote Machine

1. Go to Remote Machines.
2. Generate or import the system key.
3. Add a remote machine.
4. Enter host, port, username, and optional default path.
5. Deploy the public key or copy it manually.
6. Test the connection.

Example:

Host: backup.example.com
Port: 22
Username: backup
Default path: /backups

Setup Presets

The deploy dialog includes setup presets for Linux servers, BorgBase, Hetzner Storage Box, and NAS targets such as Synology and Unraid. Presets prefill provider-aware placeholders and editable defaults like port, deployment mode, default path, SSH path prefix, and mount point. They do not fill passwords or private account IDs. Review provider-specific path details in Provider Guides before saving.

Connection Options

Common options:

Option	Use when
Default path	File browsing should start from a specific remote directory
SFTP deployment mode	Key deployment needs SFTP mode, for example Hetzner Storage Box
SSH path prefix	SSH commands need a prefix that SFTP browsing does not, for example some NAS paths
Logical mount point	You want a friendly name for the remote machine in path pickers
Use sudo	SSHFS access needs the remote SFTP server to run through sudo

SFTP deployment mode can break some older SSH servers or NAS devices. Disable it when key deployment fails on those systems.

Remote Machines can also refresh storage usage by running df on the remote host.

Connection Diagnostics

Use the diagnostics action on a configured remote machine when a connection test passes but backups or remote services still feel slow or unreliable.

Diagnostics report:

• SSH session health and elapsed time
• latency for a simple remote command
• optional TCP reachability from the remote machine to a host and port
• bounded SSH download throughput with clear units

The TCP target is optional and lives under Advanced: test another service. Leave it blank for a basic SSH and speed check, or enter a service host and port such as postgres.internal:5432 to verify whether the remote machine can reach a dependency from its own network. Optionally adjust the timeout in seconds to control how long the remote TCP check waits before reporting a timeout.

Manual Public Key Install

On the remote server:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA... borg-ui" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Use a dedicated remote user where possible.

Repository Paths

When creating or importing SSH repositories, use paths that Borg can access through the selected remote connection.

Examples:

backup@example.com:/backups/laptop
ssh://backup@example.com:22/backups/laptop

For Hetzner Storage Box-style paths, keep the provider-specific path syntax:

ssh://u123456@u123456.your-storagebox.de:23/./backup-repo

Use /home as the Remote Machine default path for Storage Box browsing and key deployment. Keep /./backup-repo or /./borg-repository as the repository path syntax when creating or importing the Borg repository.

For BorgBase, repository URLs commonly use /./repo:

ssh://abcd@abcd.repo.borgbase.com/./repo

Use /./repo as the Remote Machine default path and repository path. Do not shorten it to /repo. Add Borg UI's full public key in BorgBase SSH Keys and grant that key access to the repository; BorgBase SFTP Access is not required for Borg UI's Borg-over-SSH repository setup. See Provider Guides for BorgBase, Hetzner Storage Box, Synology, Unraid, and other hosted or NAS examples.

Remote Direct Backups

When a backup plan uses an SSH source and an SSH repository on the same SSH connection, Borg UI runs borg create on that remote machine and sends data directly to the repository. This avoids SSHFS pull mode and keeps high-I/O source reads on the remote/source host where the data resides instead of the Borg UI Docker host.

Use the connection's Borg binary path when the source host needs a wrapper script, for example to pause Docker containers before Borg starts and resume them after Borg exits. The repository remote_path setting is different: it is passed to Borg as the repository-side remote Borg path.

Synology and NAS Path Prefixes

Some NAS devices expose different paths over SFTP and SSH. Synology DSM is a common example. For provider-level mapping notes, see Provider Guides.

SFTP path shown while browsing: /playbackup/borguitest
Path Borg needs over SSH:       /volume1/playbackup/borguitest

In this setup, configure the remote machine like this:

Default path: /playbackup
SSH path prefix: /volume1

Then select or enter repository paths using the SFTP-visible path, such as /playbackup/borguitest. Borg UI keeps SFTP browsing in that namespace and prepends the SSH path prefix only when it builds SSH/Borg commands.

If repository initialization fails with an error like The parent path of the repo directory [...] does not exist, compare the path shown by SFTP browsing with the full path needed by Borg over SSH. Put only the missing leading segment, such as /volume1, in SSH path prefix. Do not include that prefix again in the repository path, or the generated SSH path may be wrong.

Import an Existing Key

If you import from the host filesystem, mount the key read-only into the container first:

docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -e REDIS_HOST=disabled \
  -v borg_data:/data \
  -v ~/.ssh:/host-ssh:ro \
  ainullcode/borg-ui:latest

Then import from a path such as:

/host-ssh/id_ed25519

Passphrase-protected keys are not suitable for unattended scheduled backups unless the UI flow explicitly supports your setup.

Restrict Remote Access

For backup-only remote users, consider restricting the public key in authorized_keys:

command="borg serve --restrict-to-path /backups",restrict ssh-ed25519 AAAA... borg-ui

Adjust the path for your server.

Troubleshooting

Connection test fails

• verify host and port
• verify the public key is installed for the correct user
• check remote file permissions on ~/.ssh and authorized_keys
• check that the container can reach the host

Permission denied during backup

The remote user needs read access to source paths and write access to repository paths.

Host key changed

Verify the host change first. Then update known-hosts through the UI or by reconnecting as appropriate.