Guth Sync
Guth Sync is the rsync command plugin for Guth and guth-cli. It keeps the transport simple: OpenSSH encrypts and authenticates the connection, while rsync performs bounded one-way transfers between matching UUIDv7 profiles.
Guth Sync currently supports Unix systems with OpenSSH and rsync 3.2.5 or newer.
Install
Both machines need OpenSSH, rsync 3.2.5 or newer, guth-cli, and guth-sync:
Create a dedicated SSH key for Guth Sync and restrict it on the receiving machine instead of granting it a shell:
Use --identity ~/.ssh/guth-sync when transferring. The generated entry uses OpenSSH's restrict option and a forced Guth Sync command. An unrestricted SSH account remains fully trusted and can bypass application-level folder boundaries, so a shared profile key is not protection from a user who already has shell access to that account.
Pair Two Folders
Create a profile on the first machine:
Display and transfer the reusable pairing credential through a trusted channel. On the other machine:
Paste the pairing code at the hidden prompt. The UUID and 256-bit key must match on both machines.
For headless provisioning, guth-sync join ~/Sync --code-stdin reads the code from a bounded standard-input pipe instead of process arguments.
Transfer
Push or pull the whole profile:
Transfer selected relative paths:
Use --port N for an SSH service that does not listen on port 22. --identity, --known-hosts, and --remote-program accept safe absolute paths for restricted or nonstandard SSH installations. SSH host-key checking is strict; establish the host's key through a trusted channel before transferring.
The remote SSH account must have guth-sync in its command path. Guth Sync invokes a short-lived rsync server through SSH; it does not open a separate listening port. Transfers preserve destination-only files because destructive rsync deletion options are not exposed.
Privacy Model
- Profiles are stored below
$XDG_CONFIG_HOME/guth-sync/profiles, or~/.config/guth-sync/profiles, in user-only directories and files. - Guth Sync stores only the profile UUID, root path, and matching transfer key. It does not store endpoints, hostnames, IP addresses, session identifiers, transfer history, filenames, or logs.
- Plugin manifests contain only the public UUIDv7 plugin identity and executable metadata.
- Local commands are spawned directly without
sh -c; remote command components are strictly validated. Secrets are not placed in process arguments. - Temporary rsync configuration and password files are mode
0600and removed after normal completion. Abrupt process or machine termination can leave a private temporary file for manual cleanup.
A direct SSH transfer cannot hide network metadata. Each peer, network infrastructure, and the remote SSH service can observe connection addresses, timing, and traffic volume; sshd may keep system logs. Use a trusted VPN, jump host, or anonymity network when endpoint privacy is required. Guth Sync makes no claim that direct transfers conceal IP addresses.
Endpoints are not written to Guth Sync files, but an endpoint supplied on the command line can appear in shell history and the local process table while rsync is running. This is unavoidable for the direct SSH connection model.
Safety
Guth Sync rejects absolute and parent-traversing transfer paths, profile roots containing control characters, unsafe profile permissions, symlinked profile files, malformed endpoints, mismatched profile keys, and non-SSH host activation. Pull is not integrated with Guth's undo stack, so dry-run and backups remain appropriate for important data.
Profile trees must not be concurrently rewritten by untrusted local processes during a transfer. Guth Sync rejects stable source-path symlink traversal, but rsync operates on a live filesystem rather than a transactional snapshot.