Browsing files

File list, drag and drop, moving and renaming, extract, delete, vault size and mounting from inside the vault.

The Browser is where you spend most of your time once a vault is open. It lists the folder of the vault you are in, with the vault name, the current path and the cipher at the top and the action buttons on the right of the top bar.

Toolbar actions

The file list

Folders come first, then files, each group sorted by name, with a folder or file icon in front of each name. Files show their size on the right.

• Click a row to select it. Double-click a folder, or select it and press Enter, to open it.
• < parent dir at the top of the list goes up one level.
• An empty folder shows Empty folder. Drop files here, or right-click for actions.

Context menu

Right-click an entry:

Right-click the empty area below the entries for New folder..., Add file... and Refresh (re-read the folder).

Rename and move

• Rename: right-click > Rename, or select the entry and press F2. The name turns into a text field with the name selected, minus its extension, so typing replaces the name and keeps .pdf, .txt and so on. Enter (or clicking elsewhere) applies the new name, Esc cancels.
• Move: drag an entry onto a folder to move it into that folder, or onto < parent dir to move it up one level. Right-click > Move to parent folder does the same as the latter.

Renaming or moving an entry onto a name that already exists in the target folder is refused with an "already exists" error, so nothing is ever replaced (0.6.0+; older versions silently replaced the existing file).

Drag and drop

Into the vault (0.6.0+). Drag files, or whole folders, from your file manager (Explorer, Finder, Nautilus, Dolphin, ...) onto the file list. The list lights up with Drop to encrypt into ..., and on drop everything is encrypted into the folder you are viewing.

• Folders are imported with everything inside them.
• Symbolic links are skipped, never followed (so a link cannot pull in files from outside what you dropped), and so are sockets, pipes and device files. A warning says how many entries were skipped.
• If a dropped file or folder has the same name as an entry already in that vault folder, the import stops there with "... already exists in the vault folder": nothing is merged or overwritten. What was imported before that point stays in the vault, and the message says how much.
• Works on Windows, macOS, X11 and native Wayland sessions (GNOME, KDE). On Wayland the windowing library LUKSbox uses delivers no file drops, so LUKSbox listens for them itself on the window's Wayland connection; set LUKSBOX_GUI_NO_WAYLAND_DND=1 to turn that listener off.
• Drops only work on the Browser of an open vault.

Inside the vault. Drag an entry onto a folder, or onto < parent dir, to move it (see above).

Out of the vault: not supported. Dragging a file from the Browser onto your desktop or into a file manager would make LUKSbox write the decrypted file to a temporary location first, leaving plaintext copies on disk. To get files out, use Download... / Download (recursive)..., or mount the vault as a drive (below) and use your file manager's own drag and drop on the mounted drive.

When the system file chooser does not open

On Linux the file chooser comes from the XDG desktop portal (on GNOME xdg-desktop-portal-gnome, which uses Nautilus), with zenity as a fallback. When neither can be shown, LUKSbox says so ("The system file dialog could not be opened (...). Type the path instead.") instead of silently doing nothing (0.6.0+):

• + Add file..., Download..., Download (recursive)... and Mount as volume... open a box where you type the path (~ stands for your home folder).
• Open existing... takes you to the Unlock view with an empty path field, as Type path manually... in the sidebar does.
• The Browse... buttons of the Create, Unlock and Panic forms and of the add-keyslot dialogs show the message: type the path into the field next to the button.

Set LUKSBOX_GUI_TYPED_PATHS=1 to skip the system file chooser altogether and always type paths, for example when the portal hangs instead of failing. Installing zenity gives LUKSbox the fallback dialog (the .deb and .rpm recommend it).

Vault size

Vault size (0.6.1+) shows how big the vault file is (File size), the fixed part holding the header and the encrypted file tree (Metadata (fixed)), how much of it holds your files (Used by files), how much is free inside it (Free inside), and the free space left on the disk (Disk free).

• Maximum size: drag the slider (far left is Unlimited, far right the disk's free space) or type an exact value next to it (6G, 500M, 1.5G, 0 for unlimited), then click Apply maximum size. The line under the field shows what the value was understood as (= 6.0 GB (6,442,450,944 bytes)). Writes that would grow the vault past the limit fail as on a full disk; free space inside the vault is still reused. A vault with a maximum size needs LUKSbox 0.6.1 or later to open; set it back to unlimited if an older version must open it.
• Give back: when the end of the vault file is unused (for example after deleting the last files you added), Give back ... cuts it off. Free space in the middle stays inside the vault for new files. Not offered for a vault opened in recovery mode.
• When locking or unmounting a vault: Ask (from 1 MB) (default), Always or Never give back the free space at its end. With Ask, LUKSbox asks "Give back free space?" when at least 1 MB can be freed, with a Remember my choice box: when you lock a vault you are browsing (Lock, or opening or creating another vault, which locks it first), and when the unmount finishes for a mounted one. On macOS with FUSE-T the mount runs in a helper process that cannot ask, so there only Always applies.

Deniable vaults

A deniable vault is never shrunk on its own: anyone who sees the file at two points in time (backups, sync history, disk images) would learn from a smaller file that data was deleted, about how much, and when. The Ask / Always / Never setting never applies to it (its Vault size dialog does not show it), and nothing is given back when you lock or unmount it.

If you accept that risk, the dialog shows how much is unused at the end of the file: tick I understand that a smaller file reveals deletions, then click Give back ... anyway (0.6.1+).

Mount as a real drive

The Browser toolbar (top-right of the vault view) has two mount buttons. The first, "Mount as volume...", opens a folder picker; pick an empty directory and LUKSbox mounts the vault there. On Windows it picks the next free drive letter (from Z: down) instead of asking for a folder. The second is macOS + FUSE-T only.

"Eager flush (--sync)" checkbox

Next to the mount buttons is an Eager flush (--sync) checkbox. It controls the flush policy of the next mount session:

• Unticked (default): deferred flush. Mutating ops (create, rename, delete, etc.) mark the in-memory tree dirty and return immediately; a background timer persists changes every 30 seconds. This is what makes basic file-manager operations (rm, drag-and-drop a folder) fast on vaults with thousands of files. A host crash without explicit fsync can lose up to 30 seconds of metadata changes.

• Ticked: eager flush. Every metadata mutation is flushed to disk before the operation returns, restoring pre-v0.2.2 per-op durability. Cost scales with total file count, so on large vaults this can make Finder / Explorer feel sluggish on every action. Tick only for small vaults or workflows where every change must be crash-durable on return.

The checkbox is per-mount session, not persisted: it resets to off after each mount, so eager flush is always an explicit opt-in. Mid-mount you cannot switch modes; unmount and re-tick to change.

The CLI equivalent is luksbox mount --sync and the wizard's equivalent is the "Eager flush?" prompt before mounting (see the mount reference for the full trade-off). Default is off in all three surfaces.

"Mount privately" (macOS + FUSE-T)

The second button, labelled "Mount privately", appears only on macOS builds that use the kext-free FUSE-T backend. Click it and LUKSbox mounts the vault under ~/Library/LUKSbox/Mounts/<vault-name> instead of the usual /Volumes/<vault-name>.

Why bother:

• ~/Library is mode 0700 by default, so the mountpoint path itself is invisible to other user accounts on this Mac. Useful on shared family / household machines.
• The default /Volumes/<name> is in a world-readable directory. File contents are still protected by mode 0700 on the FUSE root, but the name leaks.

What you give up:

• The mount will NOT show up in Finder's Locations sidebar (which only watches /Volumes).
• Hand-typing the path is annoying because ~/Library is hidden in Finder by default. Use the "Open mountpoint" button on the post-mount status view instead, or Finder > Go > Go to Folder.

For single-user Macs the default /Volumes mount is usually better, there is nobody else to hide from, and Finder integration is smoother.

Next

• Manage keyslots (add a backup YubiKey, rotate the MVK) ->
• Panic mode (emergency vault destruction) ->