Skip to content

Storage layout

Paw stores vaults as local files on your machine. Each vault has an encrypted index, separately encrypted item files, and encrypted attachments.

File locations

Paw stores all its data in a single .paw directory. The default location depends on the platform:

PlatformDefault location
Linux~/.paw/
macOS~/.paw/
FreeBSD~/.paw/
Windows%USERPROFILE%\.paw\ (for example, C:\Users\Alice\.paw\)

To use a different parent directory, set the PAW_HOME environment variable: Paw then stores its data in $PAW_HOME/.paw/ (on Windows, %PAW_HOME%\.paw\). Both the desktop app and the CLI resolve the directory the same way, so they always share the same storage.

Application directory layout

The root application directory contains:

PathPurpose
storage/Directory containing all local vaults
paw.jsonApplication state and settings (unencrypted)
agent.sockUnix domain socket used by the agent (\\.\pipe\paw named pipe on Windows)
paw.lockProcess lock file preventing concurrent GUI instances
paw.logApplication event log

Vault directory structure

Each vault is stored under storage/<VAULT_ID>/ with the following structure:

File / DirectoryPurposeEncryption
identities/scrypt.ageMaster hybrid post-quantum age private identityPassword-encrypted (scrypt)
vault.ageIndex containing item summariesEncrypted with vault key
items/Encrypted item revision filesEncrypted with vault key
files/Encrypted file attachmentsEncrypted with vault key
sync.ageDevice-specific sync identity (ML-DSA-44 private key)Encrypted with vault key
sync-peers.ageTrusted peer pairing records (device names and ML-DSA public keys)Encrypted with vault key
metadata.jsonVault name, icon, and display colorUnencrypted (used to display locked vaults)
Sync identity warning: sync.age is unique to your local device. Do not copy it to another device. To transfer a vault to a new device, use Sync clone or export a .paw backup.
Do not edit or remove vault files manually while Paw is running.

Selecting a vault in the CLI

Each vault has a unique 16-byte identifier, displayed by Paw and used on the filesystem as a lowercase Base32 string (for example, mjqxgz2rn...).

Commands that select an existing vault accept any of the following:

  • The exact vault name (for example, Personal).
  • The full Vault ID.
  • A unique Vault ID prefix of at least 7 characters (for example, mjqxgz2).

For example, paw cli unlock Personal and paw cli unlock mjqxgz2 both open the same vault. The paw cli ls command displays vault names together with their ID prefixes: Personal (mjqxgz2).