Clipboard → Devices → File

In normal use, Clipshot watches your clipboard.

When you copy something:

• text is synced as text
• images and files are saved locally and shared to peers
• peers receive the same item and store it locally

On a desktop the newest item takes the clipboard, ordered by the time it was copied, not the time it arrived — on a mesh a forwarded copy can overtake a direct one, and an older item that arrives late is kept in the feed on Home without touching your clipboard. On a phone or tablet an arrival is an offer and never writes the pasteboard by itself; see Phones and tablets.

Clipboard detection never blocks on network I/O. Clipshot uses a BroadcastQueue (bounded FIFO) to separate clipboard polling from network delivery. The tick loop runs in stages: Clipboard → FastOps → IncomingAndGossip → BroadcastPending → SlowReconnect. The clipboard stage detects changes and queues them; the broadcast stage sends them to peers.

You can control the queue size in Settings → Sync → Broadcast queue size (1-10, default 1). At 1, a new copy replaces the previous pending item.

File storage (~/.clipshot/sync/)

Clipshot keeps synced files in a local folder:

~/.clipshot/sync/

This folder is where received files and synced clipboard assets are stored.

Consistent filenames: the sender generates filenames like img_20260502_339b.png (date + content hash). The receiver uses the same filename, so identical content has the same name across all devices.

Big items resume after a drop

A dropped connection is ordinary weather on a slow or relayed path, so a big item is built to survive one rather than avoid it.

• An item of 8 MiB or more travels in 1 MiB chunks. The receiver keeps what it has in a partial file under <received files dir>/.partial/ and, when the same item is offered again — by the same device or by any other device forwarding it — answers with the offset it already holds. The sender continues from there; nothing is sent twice.
• After a mid-item drop the sender resumes on its own, up to 3 times within the item’s own time budget (15 s plus 5 s per MiB). A device that cannot be reached at all is a dead link, not an interruption: one quick retry, then the item is marked failed for that device (catch-up on reconnect can still bring it, see below).
• The Transfers list shows one row per item and device for the whole chain: the row stays in progress across a drop, the byte count never goes backwards, and on the receiving side the row names the device that finished it. A drop is logged as information, not as a warning.
• A device on an older build that does not understand the chunked form gets the same item in one stream instead.
• A share from the iOS share sheet takes the same path: a big item resumes within the time the sheet gives that device; a busy or unreachable device means the next device is tried. If the sheet is closed or killed mid-item, the partial stays on the desktop and is continued by the next send of the same item — sharing it again, or the forward from the device that did receive it.
• Partials are kept for 15 minutes of inactivity, at most 32 files or 2 GiB in total.

What does not resume yet, stated plainly:

• items under 8 MiB are sent in one stream and restart from zero after a drop (bounded by the same time budget);
• the Pro Send File action switches to chunked, resumable streaming at the same 8 MiB (one threshold for both); its resume continues only when the same queued job retries — a file you send again after the job has failed starts from zero.

Catch-up on reconnect

When a device connects, each peer offers it the single newest clipboard item that device has not received yet (latest wins — the item you would want on the clipboard, not a replay of everything copied while it was away). A device that already has the item answers so in one round trip. There is no setting for this.

Outbox for offline peers

If another device is temporarily offline, Clipshot keeps recent syncable items long enough to retry when that device comes back.

In practice, this means you do not always need to recopy the same item after a short disconnect.

Mesh forwarding

If device A can’t reach device C directly, but both can reach device B — data flows through B automatically. No configuration needed. This works for text, images, and files of any size.

Each forwarded message carries an origin ID and hop count (TTL). Content is deduplicated - the same item is never delivered twice. Maximum 5 hops.

Encryption & Security

All data travels over QUIC with TLS 1.3 encryption - the same technology used by Google and Cloudflare. Content is encrypted in transit between your devices.

What’s encrypted:

• All clipboard content (text, images, files)
• Peer-to-peer handshake and data transfer
• Relay-forwarded traffic (relay sees encrypted packets, not content)

What’s NOT encrypted at rest:

• Files in ~/.clipshot/sync/ are stored unencrypted on disk
• Settings in ~/.config/clipshot/ are plaintext TOML

Group isolation:

• Each account has a group_token - only devices with the same token can discover each other
• Peer relay only forwards traffic within the same group
• A node from another account on the same network cannot see your devices, intercept your data, or use your node as a relay
• mDNS discovery verifies group membership during handshake - mismatched nodes are rejected
• The portal never sees clipboard content - only device metadata for discovery

Relay privacy:

• Central relay (relay.clipshot.cc) forwards encrypted QUIC packets - it cannot read content
• Peer relay (embedded on each node) only serves group members
• N0 public relay (iroh) - same: encrypted passthrough, no content access

Post-quantum (opt-in):

• Build with cargo build --features pq to enable ML-KEM + X25519 hybrid key exchange
• Protects against future quantum computer attacks on key exchange
• Default builds use standard TLS 1.3 (lighter, better cross-compile support)