Sync a large folder between two servers (resumable, in the background)

Last updated: 2026-07-08

You have a large folder — tens of gigabytes — on one server and you want an exact copy on another. You can't watch a terminal for hours, and a transfer that dies halfway shouldn't start over from zero. relayium sync is built for this: a one-way incremental mirror that skips what's already there, resumes a half-sent file from where it stopped, and verifies every file end to end.

This guide sets up an unattended, self-healing transfer: authorize the sender once, run the listener in the background, and drive relayium sync from a retry loop inside tmux so it keeps going across dropped connections until the whole folder has landed.

Why relayium sync fits this job

sync is a one-way incremental mirror over the native protocol (install relayium on both ends). Three properties make it safe to run and re-run unattended:

Skips files already there: a file whose copy on the receiver matches by size and modification time isn't sent again.
Resumes partial files: if a file was half-transferred when the connection dropped, the next run continues from the byte offset already on disk instead of restarting it.
Verifies every file: each file is checked with SHA-256 end to end, so a completed mirror is known to be intact.
Because of these, the command is idempotent — running it again only does the work that's left, which is exactly what lets a retry loop finish a huge transfer.

Prerequisites

Install relayium on both servers (sync speaks the native protocol, so it must be present on each end):

# on BOTH servers
curl -fsSL https://relayium.com/install.sh | sh

This guide uses daemon direct (relayium://), so the two servers don't need SSH access to each other.
Open the listener's port (9031 by default) to the sender on the receiver's firewall or security group.

Authorize the sender once (on the receiver)

The receiver approves the sending machine one time; the approval is written to disk and stays valid across restarts, so you never repeat it. Start the listener in a terminal, and point --dir at the parent directory — relayium sync /root/workspace reproduces workspace/... on the receiver, so --dir /root lands the files at /root/workspace/.

On the sender's first connection (next section), serve shows its address and fingerprint and asks you to approve it; answer y and it's remembered for good:

# on the RECEIVER (foreground, to approve interactively)
relayium serve --dir /root --port 9031

# on the RECEIVER, at the first connection:
Incoming push from 203.0.113.9:52140
  fingerprint: 9f2c41ab…
Accept and remember this peer? [y/N] y

For a fully unattended setup, skip the prompt: run relayium id on the sender to print its fingerprint, then relayium authorize <fingerprint> on the receiver.
--dir is the parent of the folder you're syncing, not the folder itself — otherwise files land one level too deep (e.g. /root/workspace/workspace).

Run the listener in the background (on the receiver)

Once the fingerprint is authorized, stop the foreground serve (Ctrl-C) and re-launch it detached so it survives your logout. It loads the saved fingerprint and accepts the sender silently — no prompt this time:

# on the RECEIVER
nohup relayium serve --dir /root --port 9031 > ~/relayium-serve.log 2>&1 &

serve handles connections one at a time and keeps running, so it's ready for every reconnect from the retry loop below.
For an always-on inbox, run it under systemd instead (Restart=always, --config-dir /etc/relayium).

Run the sync in a retry loop under tmux (on the sender)

Long transfers get interrupted — a dropped session, a flaky network, a reboot. The fix isn't a fancy tool; it's a loop that reruns sync until it succeeds, plus a terminal multiplexer so it survives you logging out. tmux is cleaner than nohup here: no output redirection to get wrong, and you can reattach to watch progress.

Start a tmux session, then run the mirror in an until loop — it retries every 10 seconds until sync returns success, then exits on its own:

# on the SENDER
tmux new -s xfer      # apt install -y tmux if it's missing

until relayium sync /root/workspace relayium://203.0.113.43:9031; do echo "$(date) retrying"; sleep 10; done

Detach with Ctrl-b then d; the loop keeps running after you close the terminal. Reattach with tmux attach -t xfer.
Each retry does less: already-transferred files are skipped, a half-sent file resumes — so the loop converges and finishes.
Progress prints one line per completed file, so a big file transfers quietly until it's done. Silence isn't a stall (see troubleshooting).

Verify and finish

The transfer is complete when the until loop ends and you're back at a normal shell prompt. Confirm both sides match, then stop the listener:

# compare totals on BOTH servers
du -sh /root/workspace

# on the RECEIVER, once verified
pkill -f 'relayium serve'

Every file was SHA-256 checked on arrival, so matching sizes plus a clean exit means an intact copy.

Troubleshooting

A few things that look like problems but usually aren't — and the one that usually is (a blocked port).

No output isn't a stall. Progress prints only when each file finishes, so a large file transfers silently. Check the real state on the sender with ss -tnp | grep 9031 — ESTAB means it's connected and transferring; SYN-SENT means it can't reach the listener.
SYN-SENT means the port is blocked. Open 9031/TCP to the sender on the receiver (cloud security group, or ufw allow 9031/tcp). This is the most common cause of a transfer that never starts.
Prefer tmux plus a single-line loop over multi-line nohup. Pasting a multi-line command with quotes and a > redirect into a shell often breaks on the redirect or leaves you at a > continuation prompt.
When cleaning up processes, match precisely (pkill -f 'relayium sync'), not pkill relayium — a broad match can kill an unrelated relayium process running on the same box.
venv and other regenerable directories are worth excluding. A Python virtualenv can hold gigabytes of libraries that pip recreates on the far side; skipping them saves a lot of transfer.
Symlinks and special files are skipped — sync transfers regular files only. Handle any important symlinks separately.

Frequently asked questions

What happens if the transfer is interrupted halfway?

Nothing is lost. Rerun relayium sync — it skips files already on the receiver and resumes a half-sent file from the byte offset already on disk. The until loop in this guide does that automatically until the whole folder is mirrored.

How is this different from rsync?

Both do incremental one-way mirroring, but relayium sync runs over a pinned TLS connection with no SSH account required (daemon direct), authenticates the two machines by certificate fingerprint, and verifies every file with SHA-256. It's the same transfer engine as relayium's other modes.

Does sync delete files on the receiver that I removed from the source?

Only if you ask. By default sync only adds and updates. Pass --delete to mirror deletions, and the receiver must run serve with --allow-delete for it to be honored — otherwise the delete is ignored and reported back.

Can I keep two folders in sync continuously?

Yes. Add --watch and sync stays running, re-mirroring on any change under the source. For a one-time move of a large folder you don't need it — the retry loop plus a plain sync is enough.

Do I have to open a port?

For daemon direct, yes — the listener's port (9031 by default) must be reachable from the sender. If you'd rather not open a port and already have SSH between the servers, sync also works over SSH: relayium sync /path user@host:/path (relayium must be installed on the remote).

Mirror a folder between two of your own servers — incremental, resumable, no babysitting.

Get the CLI