Usage

Usage

VaultBar lives in the menu bar and has no Dock icon.

The menu bar icon

State	Icon
Everything locked	Monochrome notebook with a closed padlock
Any vault unlocked	Amber open padlock (however it was mounted: VaultBar, Finder, Terminal)
Auto-lock paused	Orange warning badge

• Left-click: lock or unlock the default vault.
• ⌥-click: lock every vault (asks before forcing a busy one).
• Right-click (or Control-click): the menu.

Menu

• One entry per vault, showing its state (Locked / Unlocked / Unlocked (read-only)) with Unlock… or Lock, and Open in Finder (when locked: Unlock & Open…). Hold ⌥ to swap Unlock… for Unlock Read-Only… (or Unlock Read-Write… for a vault that unlocks read-only by default).
• Lock All
• Pause auto-lock for 1 hour (becomes "Auto-lock paused until … — Resume" while active)
• Last: … (the latest event) and History…
• New Vault…, Add Existing Vault…
• Settings…
• About VaultBar, Support on Ko-fi
• Quit VaultBar

Unlocking and locking

1. Start an unlock by left-click, the menu, or a vaultbar://unlock link.
2. The password popup takes the keyboard at once, so you can type right away. Enter unlocks, Esc cancels. Paste works.
3. The vault mounts in Finder like any disk.

A wrong password shows "Wrong password. Try again." and reopens the popup.

Open in Finder after unlocking (Settings, off by default) opens the vault in Finder after every unlock: the menu bar click, the menu's Unlock…, vaultbar://unlock and the Raycast Unlock script. Open in Finder / Unlock & Open…, vaultbar://open and the Raycast Open script always open it.

Locking cleanly unmounts the vault. If it is busy (a file is open), VaultBar asks before forcing. Forcing can lose unsaved changes in open apps.

Read-only unlock

Turn on Read-only for a vault in Settings to unlock it read-only by default, or choose it once: ⌥ in the menu, vaultbar://unlock/<name>?readonly=1, or vaultbar unlock <name> --readonly. Whichever way it starts, the password prompt shows the mode at the top ("Work — Read-Only" with a blue icon, "Work — Read & Write" with an amber one) and a Read & Write | Read-Only switch: flip it with the mouse or ⌘R before pressing Enter, without leaving the password field. A wrong-password retry keeps the mode you chose. Nothing can be written to a read-only mount, and forcing it to lock can't lose anything. To switch modes, lock and unlock again.

Private mount, hidden from Finder

By default macOS mounts a vault at /Volumes/<volume name> (and renames it <volume> 1 if the name is taken). In Settings, Private Folder… picks a parent folder, and the vault then mounts at <that folder>/<vault name>, a path that never changes. Hidden from Finder mounts it with -nobrowse: not in Finder's sidebar, the Desktop or other apps' file pickers (you can still open it with Open in Finder).

The folder exists only while the vault is unlocked. VaultBar creates it (mode 700) right before unlocking and removes it (only if empty) right after locking, including when the vault is ejected outside VaultBar (Finder, hdiutil detach, another app; checked on every unmount and every 30 s), so a locked vault leaves no empty folder that you or an app could write plaintext into by mistake. It refuses a folder that isn't empty and any folder that syncs to a cloud.

Panic lock

A global hotkey locks every vault at once: ⌃⌥⌘L by default, or ⌃⌥⌘K, ⌃⇧⌘L, ⌥⇧⌘L, or off (Settings → Panic lock). It needs no Accessibility permission. With Force busy vaults on (default), vaults with open files are force-locked, which can lose unsaved changes; turn it off to be asked instead. vaultbar://lockall and vaultbar lock --all lock everything too (asking before forcing).

Notifications and history

VaultBar notifies you when idle or screen-lock auto-lock locks a vault (sleep locks are silent), a minute before it force-locks one that is still in use after you've gone idle (with a Keep unlocked 15 min button that pauses auto-lock), and when a lock fails (sleep included). The wording never names a vault, since notifications can show on the lock screen. If you deny notifications, nothing else changes.

The menu shows the latest event; History… lists the last 50 (unlocks, locks and their reason, forced locks, failures, pauses). History is kept in memory only and cleared when VaultBar quits.

Change password

Settings → a vault → Change Password… (the vault must be locked). Enter the current password and the new one twice; VaultBar warns about passwords under 12 characters or containing the vault's name. It runs diskutil image chpass with both passwords on stdin, then checks that the new password opens the image (read-only, hidden, locked again right away).

This changes the password that opens the image; it doesn't re-encrypt the data. Copies of the image made before (backups, snapshots) still open with the old password. For a full re-key, create a new vault and copy the files over.

The unlock prompt

At the top the prompt shows the vault and the mount mode, with the Read & Write | Read-Only switch (⌘R). Under the password field it shows Caps Lock is on and the current keyboard layout, the usual reasons a correct password is rejected. VoiceOver announces the prompt with its mode when it appears, and the new mode when you switch it.

New Vault…

Creates an encrypted AES-256 APFS sparse bundle. You choose a name, a folder, a maximum size in GB (default 100; the file starts small and grows) and a password. The volume name is optional and defaults to the vault name.

• Save the password in your password manager first. There is no recovery key.
• It warns about passwords under 12 characters.
• It warns about folders that sync to a cloud: iCloud Drive, Desktop & Documents, ~/Library/CloudStorage, Syncthing and Synology Drive folders. See FAQ.
• After creating, stop Spotlight from indexing it (VaultBar shows the command with a Copy button):

sudo mdutil -i off "/Volumes/<volume name>"

Add Existing Vault…

Any encrypted .sparsebundle or .dmg. Unencrypted images are rejected, and a vault already in the list is refused.

Auto-lock

Applies to every vault. Set in Settings….

Trigger	Behaviour
Sleep	Forced, immediately
Screen lock	Clean unmount; if a file is still open, forced after 30 s, but only if the screen is still locked
Idle for N minutes	Clean unmount; if busy, forced after 60 s, but only if you're still away

The screen-lock and idle locks re-check before forcing, so coming back cancels the force. Idle time counts keyboard and mouse only. 0 idle minutes turns idle locking off.

Pause auto-lock for 1 hour

For long unattended jobs that work inside a vault. Idle and screen-lock auto-lock are skipped; sleep still locks. The icon gets a warning badge. The pause ends after an hour, on Resume, or when VaultBar quits (it is never saved).

Config

~/.config/vaultbar/vaults.json (mode 600, never holds a password). Settings edits it for you:

{
  "defaultVault": "Personal",
  "autoLock": { "onSleep": true, "onScreenLock": true, "idleMinutes": 15 },
  "launchAtLogin": true,
  "raycastScriptsDir": "~/Raycast",
  "openAfterUnlock": false,
  "panicHotkey": "ctrl-opt-cmd-L",
  "panicForces": true,
  "vaults": [
    { "name": "Personal", "imagePath": "~/Vaults/Personal.sparsebundle" },
    { "name": "Work", "imagePath": "~/Vaults/Work.sparsebundle",
      "mountPoint": "~/Vaults/mnt/Work", "hidden": true, "readOnly": true }
  ]
}

• idleMinutes: 0 turns idle locking off. raycastScriptsDir is optional (no scripts without it).
• openAfterUnlock: true opens the vault in Finder after every unlock (default false).
• Per vault, all optional: mountPoint (private mount folder), hidden (-nobrowse), readOnly (default unlock mode).
• panicHotkey: ctrl-opt-cmd-L (default), ctrl-opt-cmd-K, ctrl-shift-cmd-L, opt-shift-cmd-L or off; panicForces: false asks instead of forcing.
• Vaults are matched by their image file, so a volume that macOS renamed to Personal 1 still shows the right state.
• Removing a vault in Settings only removes it from the list. VaultBar never deletes an image file.

URL scheme

vaultbar://unlock/<name>
vaultbar://lock/<name>
vaultbar://toggle/<name>
vaultbar://open/<name>
vaultbar://unlock/<name>?readonly=1
vaultbar://lockall

The name is URL-encoded (My%20Vault); an empty name means the default vault.

Action	Vault locked	Vault unlocked
unlock	Password popup (then Finder, if Open in Finder after unlocking is on)	Nothing
lock	Nothing	Locks (asks before forcing a busy vault)
toggle	Like unlock	Like lock
open	Password popup, then opens it in Finder (Cancel does nothing)	Opens it in Finder
lockall	Locks every vault (no name; asks before forcing a busy one)

?readonly=1 (or 0) overrides the vault's read-only setting for that unlock. The same actions are on the command line.

Raycast

Pick your Raycast script directory in Settings → Raycast Script Commands. VaultBar then keeps three scripts per vault there, Unlock, Lock and Open (vaultbar-unlock-<slug>.sh, vaultbar-lock-<slug>.sh, vaultbar-open-<slug>.sh). The slug is the vault name in lowercase, with spaces and symbols turned into dashes (e.g. My Vault → my-vault). VaultBar updates them on every launch and when you add, rename or remove a vault. Regenerate Raycast scripts rewrites them on demand.

Each script only runs open "vaultbar://unlock|lock|open/<name>"; the password goes into VaultBar's popup, never through Raycast. VaultBar only ever deletes scripts it wrote itself (marked # @raycast.packageName VaultBar).

Checking state from Terminal

vaultbar status        # or /Applications/VaultBar.app/Contents/MacOS/VaultBar status

See Command line.