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:
| Platform | Default 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:
| Path | Purpose |
|---|---|
storage/ | Directory containing all local vaults |
paw.json | Application state and settings (unencrypted) |
agent.sock | Unix domain socket used by the agent (\\.\pipe\paw named pipe on Windows) |
paw.lock | Process lock file preventing concurrent GUI instances |
paw.log | Application event log |
Vault directory structure
Each vault is stored under storage/<VAULT_ID>/ with the following structure:
| File / Directory | Purpose | Encryption |
|---|---|---|
identities/scrypt.age | Master hybrid post-quantum age private identity | Password-encrypted (scrypt) |
vault.age | Index containing item summaries | Encrypted with vault key |
items/ | Encrypted item revision files | Encrypted with vault key |
files/ | Encrypted file attachments | Encrypted with vault key |
sync.age | Device-specific sync identity (ML-DSA-44 private key) | Encrypted with vault key |
sync-peers.age | Trusted peer pairing records (device names and ML-DSA public keys) | Encrypted with vault key |
metadata.json | Vault name, icon, and display color | Unencrypted (used to display locked vaults) |
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.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).