Cypherrum User Guide

Cypherrum encrypts your files transparently — drop files into a virtual drive, and they’re encrypted on disk automatically. Your cloud provider never sees plaintext.

Installation

Windows

1. Download CypherrumSetup-x.x.x.exe from Releases
2. Run the installer — it installs to C:\Program Files\Cypherrum and bundles the Dokany kernel driver for drive mounting
3. Cypherrum starts automatically and appears in the system tray

macOS

1. Download Cypherrum-x.x.x.dmg from Releases
2. Open the DMG and drag Cypherrum.app to Applications
3. The first launch installs WebDAV plumbing and prompts for permissions — accept them
4. macOS Application Firewall: when first sharing a vault via Mesh, macOS may prompt to allow Cypherrum.app to receive incoming connections. Allow it — without that approval, peers on your LAN can’t reach your vault directly and traffic falls through the relay (still secure, just slower).

Linux (Debian/Ubuntu)

sudo dpkg -i cypherrum_x.x.x_amd64.deb

Or for Fedora/RHEL:

sudo rpm -i cypherrum-x.x.x-1.x86_64.rpm

Then enable the background service to start at login:

systemctl --user enable --now cypherrum

(Or open the Cypherrum GUI and toggle Settings → Service → Start at login — same effect, no terminal required.)

Launch the GUI from your application menu, or:

cypherrum

Manual install (any Linux)

sudo cp cypherrum cypherrum-service /usr/bin/
sudo cp cypherrum.desktop /usr/share/applications/
xdg-mime default cypherrum.desktop x-scheme-handler/cypherrum

Getting Started

Create a Vault

1. Click + > New vault
2. Enter a vault name (e.g. “Work Files”)
3. Choose where to store encrypted files (your Dropbox, OneDrive, or any folder)
4. Set a strong password (8+ characters)
5. Choose options (chunk size, compression)
6. Click Create Vault
7. Save your recovery key — print it, save to a USB drive, or store it in a password manager. This is the only way to recover if you forget your password.

Unlock a Vault

Click Unlock on a vault card and enter your password. The vault appears as a drive letter (Windows) or mount point (Linux).

Use Your Vault

Work with files normally — drag and drop, open, edit, save. Encryption is transparent. The encrypted files in your cloud folder sync automatically.

Lock a Vault

Click Lock, close Cypherrum, or let it auto-lock:

• Screen locks (if enabled in Settings)
• Idle timeout (configurable: 5/10/15/30/60 minutes)

Sharing Vaults

Two ways to share

A. Send to a paired contact (recommended). If you’ve paired devices via Contacts (see Contacts & Pairing), the share is delivered automatically to their inbox — no link copying needed.

1. Unlock your vault
2. Overflow menu (three dots) > Share with Contact
3. Pick a contact — Cypherrum shows a confirmation: “Sent to {contact} via {relay}”
4. The recipient gets a notification on their device and accepts in one click

B. Copy/paste an invite link. When you don’t have the recipient as a contact yet, or you want to share via email/chat:

1. Unlock your vault
2. Overflow menu > Create Invite
3. Enter the recipient’s name
4. Optionally protect with a password (for sharing over insecure channels)
5. Copy the invite link

The recipient:

1. Clicks + > Accept invite
2. Pastes the invite link
3. Enters the invite password (if set)
4. Chooses where to store the vault
5. Clicks Join

The vault syncs automatically — on the same network (LAN) or across the internet via the relay server.

Contacts & Pairing

The Contacts page lets you pair devices once and then share vaults without copying links every time.

1. Contacts (sidebar) > + Add Contact
2. On your device: Show my QR / pairing code — show this to the other person, or share the short code via secure channel
3. On the other device: Enter code — paste/scan the code
4. The other side sends a pair_ack via the relay; both sides confirm the pairing

After pairing, each side stores the other’s persistent fingerprint (a 64-character hex value derived from their TLS certificate). Future shares to that contact use this fingerprint to deliver invites directly to their inbox.

If something goes wrong (the dialog says “Contact’s stored fingerprint is corrupt”), remove the contact and re-pair.

Manage Members

• Overflow menu > Manage Members — view who has access
• Revoke — removes access and rotates the encryption key

How It Finds Peers

1. Same network — peers discover each other automatically (mDNS) and connect directly on TCP port 29747
2. Different networks — the app uses relay.cypherrum.com to look up peers
3. Behind NAT or blocked port — TURN relay forwards encrypted traffic as a fallback

For LAN direct-connect to work, TCP 29747 must be reachable on the host that’s sharing:

• Windows: the installer adds the firewall rule automatically
• macOS: approve the Application Firewall prompt the first time (or run sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/Cypherrum.app/Contents/MacOS/cypherrum)
• Linux: sudo ufw allow 29747/tcp or your distro’s equivalent

If the direct connect doesn’t work, sharing still works via TURN — just slower.

The relay never sees your encryption keys, passwords, or file contents.

Real-time Sync

When peers are mesh-shared and both vaults are unlocked, file changes on one side propagate to the other in ~1–2 seconds. Each vault card shows a small status pill next to the drive letter:

• ↻ syncing (animated) — pull in progress from a peer
• ✓ synced (green flash) — most recent pull succeeded
• ! stale (amber) — last pull failed; hover for the reason

How it works under the hood:

1. When you write a file via the mounted drive, the service collects the change and waits 800 ms for further writes from the same burst.
2. After the quiet period, it pushes a tiny vault.updated notification to each member’s relay inbox.
3. The receiving peer’s WebSocket subscription delivers the notification immediately and triggers a pull.
4. As a safety net, every peer also pulls every 60 s in case a push was missed (relay restart, peer offline at push time).

If you don’t see new files in an open Explorer/Finder window, press F5 — the OS shell isn’t notified yet. The next click on the vault card OR the next vault list refresh will show the updated state. (Kernel-level shell notification is staged for a future release.)

Conflicts

If both peers edit the same file while disconnected, they each keep their local copy. After reconnect, the incoming peer’s version is preserved alongside yours with a clear suffix:

• Yours: report.docx (untouched, your edit intact)
• Theirs: report (conflict from f78fffbf 2026-05-08 14-23).docx

The suffix uses a hyphenated timestamp (Windows disallows colons) and is inserted before the extension so file managers still open the conflict copy with the correct application.

Cypherrum never silently overwrites your edit. Both versions live in the vault — yours under the original name, theirs under the suffixed name — and you choose what to keep.

Resolving from the GUI

The vault card shows a red N conflict(s) badge when sync produced files you need to reconcile. Click it. A stepped dialog walks through each conflict with three options:

• Keep mine — discard the peer’s version. Their bytes are removed; yours stays.
• Keep theirs — replace yours with the peer’s. Your old bytes are freed.
• Keep both — promote the peer’s version to a new permanent file (default name: <stem>.from-<peerShort>.<ext>, override in the rename input). Both end up as canonical entries with their own FileID.

The dialog advances through every queued conflict; when the queue empties, the vault refreshes and the badge clears.

Resolving from the terminal

If the GUI is unreachable (headless box, frozen window, scripted batch), cypherrum-admin exposes the same operations against the running service:

# What conflicts exist?
cypherrum-admin list-conflicts oncinema

# Apply one of three actions:
cypherrum-admin resolve oncinema /                                  \
    "report (conflict from f78fffbf 2026-05-08 14-23).docx"         \
    keep_local

cypherrum-admin resolve oncinema /                                  \
    "report (conflict from f78fffbf 2026-05-08 14-23).docx"         \
    keep_remote

cypherrum-admin resolve oncinema /                                  \
    "report (conflict from f78fffbf 2026-05-08 14-23).docx"         \
    keep_both report-from-cinema.docx

The vault must be unlocked on the local service for either path to work.

Sync while the vault is locked

Default on since 0.11.0. When you accept an invite, the joiner’s per-member key is persisted to the OS keyring (libsecret on Linux, Keychain on macOS, Credential Manager on Windows) so background sync keeps working even while the vault is locked. Without this, sync would stop the moment you lock and your changes wouldn’t propagate until the next unlock — set-and-forget would mean nothing.

Toggle at Settings → vault → “Sync while locked”. Opt-out is honored.

Tradeoff worth knowing: anything running as your OS user can read the saved key and impersonate this device to the inviter’s peer server (read access to the inviter’s vault state via the mesh protocol — no plaintext access to the vault contents themselves, those need the vault password). If your threat model includes a co-tenant user on the same machine, flip it off.

Toggling it off immediately wipes the saved key from the keyring; removing the vault wipes the key plus any saved password.

Instant change notifications (joiner ↔ inviter)

Edits propagate within ~1 second in both directions on the same LAN, and within a few seconds across the relay. Behind the scenes:

• Inviter side: when files change in the mounted drive, the service fires a vault.updated push to every member in the vault.
• Joiner side (new in 0.11.0): the inviter’s relay-inbox fingerprint is captured in the invite payload and persisted as the joiner’s InviterPushRoute. When the joiner edits files, the same vault.updated push goes back to the inviter via the relay inbox.
• Both sides receive the notification, then pull encrypted bytes peer-to-peer via the mesh protocol.

A 5-second background poll runs in parallel as a safety net, so even if push delivery fails (relay outage, NAT glitch), sync still converges. Joining with a pre-0.11.0 invite link falls back to the polling path only — works, just slower.

Quick Unlock

Windows Hello

If enabled in Settings, unlock vaults with fingerprint, face, or PIN — no password typing.

Saved Password

Click the lightning bolt on a vault card for instant unlock with a saved password.

Passkey (YubiKey)

Register a hardware security key via overflow menu > Register Passkey. Tap to unlock.

Password Manager Integration

Save vault passwords to your password manager for easy retrieval:

• Overflow menu > Save to Password Manager
• Overflow menu > Unlock from Password Manager

Supported: Bitwarden, 1Password, KeePassXC, pass, LastPass.

WebDAV Access

Access your unlocked vault via a local HTTP/WebDAV server.

1. Overflow menu > Serve via WebDAV
2. Cypherrum binds a loopback-only address (127.0.0.1:<random-port>) and shows the URL + a fresh username + password in a dialog. Each session generates a new password (~96 bits of entropy); the password dies with Stop WebDAV.
3. Mount it with any WebDAV client. The dialog also shows a one-line “URL with credentials” form (http://user:pass@addr/) for clients that accept inline auth.

Loopback-only by design: even though WebDAV now requires a password, Basic Auth over plain HTTP on a LAN is still vulnerable to anyone on the wire who can sniff the request. Cypherrum binds to 127.0.0.1 so only processes on your machine can reach it. For cross-machine access, use an SSH tunnel:

# On the remote device:
ssh -L 8080:127.0.0.1:<port> you@your-laptop
# Then point the WebDAV client at http://localhost:8080/ with the same password

Future releases will add an explicit “expose on LAN with TLS” toggle — for now, treat any non-loopback bind as a defense-in-depth violation.

Importing from Cryptomator

Migrate your Cryptomator vault to Cypherrum with post-quantum protection:

1. Click + > Import vault
2. Select your Cryptomator vault folder
3. Enter your Cryptomator password
4. Choose a name and location for the upgraded vault
5. Click Upgrade

Your files are re-encrypted with AES-256-GCM + ML-KEM-768 post-quantum recovery. The original Cryptomator vault is not modified.

Backup, Restore & Moving Vaults

A Cypherrum vault is a self-contained folder on disk. Everything needed to decrypt it — the Argon2id KDF parameters, the wrapped master key, the encrypted chunks, the directory tree — lives inside that folder. The folder is portable across machines and operating systems.

What’s portable vs. per-machine

To back up a vault

Copy the encrypted vault folder to another disk, NAS, or cloud sync. Files are already encrypted with AES-256-GCM, so the backup target does not need to be trusted.

A weekly snapshot (Time Machine, restic, Backblaze, Syncthing, etc.) of the vault folder is enough. Include both the visible content and the hidden .<hex>/ subdirectory — most backup tools handle this by default; if yours hides dotfiles, enable “show hidden” or backup the whole parent.

Always also back up your recovery key separately. Without the recovery key (or your password), no backup of the encrypted folder is recoverable. The recovery key is shown once at vault creation; print it or save it to a different password manager.

To restore or move a vault

If you’ve moved the encrypted folder to a new machine, restored from backup, or just lost the registry entry:

1. Make sure the encrypted vault folder is at the path you want it (any path is fine).
2. In Cypherrum, click Attach existing vault (top-right of the vault list, or in the empty-state if you have no vaults yet).
3. Click Browse, select the parent folder of the vault — the same folder you’d back up.
4. The vault name auto-fills from the folder name; change it if you like.
5. (Windows) Choose a drive letter, or leave blank for default.
6. Click Attach. The vault appears in the list as locked.
7. Click Unlock and enter the password you used when the vault was created. (The password verifies against the master key inside vault.json — same as it does for any unlock.)

Cypherrum auto-detects the internal .<hex>/ subdirectory inside the folder you pick, so you don’t need to know its name. If the folder doesn’t contain a vault, the attach fails with a clear error and nothing is changed.

What if I move the folder while Cypherrum is running?

Lock the vault first, move the folder, then re-attach (the registered path is now stale). A future release will detect path drift and offer to re-point automatically.

What if I attach the same vault on two machines?

Both machines will read and write the same encrypted files. Cypherrum does not coordinate writes across machines that are not part of a mesh. If you write from both at once, the underlying filesystem (cloud-sync conflict copy, NFS lock loss) decides who wins. If you need true multi-host access, use the mesh-share / invite flow (Sharing Vaults section above) or a single host that exposes WebDAV (WebDAV Access section below) — both go through Cypherrum’s conflict-resolution layer.

Recovery

Forgot Password

1. Click a locked vault > Unlock
2. Click Forgot password?
3. Paste your recovery key
4. Set a new password

Health Check

Overflow menu > Health Check — verifies all encrypted chunks are intact. Run this after cloud sync errors or disk issues.

Settings

Quitting

Picking Quit from the tray menu (or closing the window on macOS) opens a confirmation dialog with a checkbox:

• Stop background sync (checked by default) — fully shuts down the service. All vaults lock; mesh sync stops.
• Unchecked — only the GUI window closes; the service keeps running so peers can pull shared vaults from you in the background. Re-open the GUI from the tray (Linux/Windows) or from the launcher (macOS — the GUI just relaunches and reattaches).

A Don’t ask me again checkbox persists your choice. Re-enable the prompt by clicking Quit again — the dialog only opens when the persisted action is “ask”, so to flip it back you’d reset QuitAction in the config.

Tray status icon

The tray icon’s bottom-right corner shows a colored disc:

• Green — service running, idle.
• Yellow — service starting / reconnecting.
• Red — service stopped or unreachable.
• Blue, pulsing — at least one vault is currently mesh-syncing.
• Green + orange badge — inbox has unread invites or pair requests.

Audit Log

Overflow menu > Audit Log — view a timeline of vault events: unlocks, locks, file changes, member additions. Stored locally per vault.

Self-Hosting the Relay

Run your own relay for full control over vault sharing.

Build and run

# From source
go build -o relay ./cmd/cypherrum-relay/
./relay --port 9473 --turn-port 9474

# With bandwidth limit (40 GB/month default; 0 = unlimited)
./relay --turn-limit 100

# Allow unlicensed users to use TURN (self-hosted home relays typically want this)
./relay --turn-require-license=false

Docker

The repo ships a Dockerfile at cmd/cypherrum-relay/Dockerfile. Build it locally — there’s no published image at logiqum/cypherrum-relay:

go build -o cmd/cypherrum-relay/relay ./cmd/cypherrum-relay/
docker build -t cypherrum-relay cmd/cypherrum-relay/
docker run -p 9473:9473 -p 9474:9474 cypherrum-relay

Flags

To point your client at the self-hosted relay, edit the relay address in your contact entries (the per-contact relay is part of pairing) or set defaultRelay for ad-hoc invites — see source.

Security Overview

Your password never leaves your device. Encrypted files are safe to store on any cloud service — even if the cloud is compromised, your data remains encrypted.

Troubleshooting

Vault won’t mount (Windows)

Check the Dokany driver is installed:

sc query dokan2

If STATE is STOPPED: sc start dokan2. If the service doesn’t exist, reinstall Cypherrum — the installer bundles the driver. Try a different drive letter if the assigned one is already in use.

Vault won’t mount (Linux)

ls /dev/fuse          # should exist
sudo apt install fuse3  # install if missing

Service won’t start (Linux)

systemctl --user status cypherrum    # check status
rm $XDG_RUNTIME_DIR/cypherrum.sock   # remove stale socket
systemctl --user restart cypherrum   # restart

Invite not working

• Sharing device must be online with the vault unlocked
• Invites expire after 24 hours by default
• If not on the same network, check relay: curl https://relay.cypherrum.com/health

Sync hangs

Check connectivity and try creating a new invite. The relay must be reachable for cross-network sharing.

Keyboard Navigation