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.
Read-Only Replicas
Protect one profile on the current machine, or make all local profiles read-only by default:
The policy belongs to this local Guth instance, so paired machines can choose different modes. A read-only local replica can push its data and can serve peer pulls. It rejects local pulls and peer pushes because those operations would modify the protected folder. Remote write-direction sessions are rejected even when the initiating peer requested a dry run. Policy changes apply to new transfer sessions and do not terminate a transfer already in progress.
The first policy change marks the local profile as policy-aware. Guth Sync 0.1.0 refuses that newer profile schema rather than bypassing protection after a downgrade, and Guth Sync 0.1.1 fails closed if a marked profile's policy file is missing or invalid. Keep $XDG_CONFIG_HOME/guth-sync/access-policy.json with the profile files when backing up or restoring this instance.
Guth exposes the same per-profile toggle from a matching Sync Folder's context menu and the all-profile toggle in plugin settings. A Sync Folder shortcut must exactly match a configured Guth Sync profile root before Guth offers the protection toggle.
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 the profile UUID, root path, matching transfer key, and local read-only policy. 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.