Backup, export, migrate¶
Everything Pluma knows about you lives in the data directory. Back that up, you've backed up Pluma.
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/pluma or ~/.config/pluma |
| Linux | ~/.config/pluma |
| Windows | %AppData%\pluma |
The quick path¶
tar -czf pluma-backup-$(date +%F).tar.gz -C "$HOME/.config" pluma
pluma -export-storage-key ./pluma-key-$(date +%F).age
The tarball has all your content + config; the key file wraps the AES-256-GCM key that decrypts conversations/*.json and credentials.json.
Both files are required to restore on a new machine. The tarball alone is useless without the key.
What's where¶
| Contains | Path inside <datadir> |
Encrypted? |
|---|---|---|
| Server config | config.toml |
No |
| LLM + image profile metadata | connections.json, image_connections.json |
No |
| Stored API keys | (in the OS keyring under connection:<id> / image:<id>) |
Per OS keychain |
| Enrolled passkeys | credentials.json |
Yes |
| Conversations + drafts | conversations/*.json |
Yes |
| Characters | characters/*.{png,json} |
No |
| Personas | personas/*.{png,json} |
No |
| Generated images | attachments/*.png |
No |
| Downloaded models | models/<repo>/... |
No |
| ComfyUI workflows | workflows/*.json |
No |
| Voice library | voices/library/*.{wav,mp3,...,json} |
No |
| Tailscale node state | tsnet/ |
tsnet-internal |
The AES key in your OS keyring is the only thing the tarball doesn't carry. Export it separately with pluma -export-storage-key <path>. The export is passphrase-wrapped (you'll be prompted), so the file at rest is safe to put alongside your tarball in cloud storage.
Restore on a new machine¶
# 1. Install Pluma on the new machine.
brew install guygrigsby/pluma/pluma # or download from releases
# 2. Unpack the backup into the data dir.
mkdir -p "$HOME/.config"
tar -xzf pluma-backup-2026-05-17.tar.gz -C "$HOME/.config"
# 3. Import the wrapped key (passphrase prompt).
pluma -import-storage-key ./pluma-key-2026-05-17.age
# 4. Start Pluma. Existing conversations decrypt on read.
./pluma
API keys aren't in the tarball — they live in the OS keyring on the source machine. On the new machine you'll need to re-enter them (or -export-storage-key is the wrong tool for this; we don't yet have a per-connection key export). They're typed once into Settings → Connections.
Passkeys are bound to the original origin + RPID. A passkey enrolled at pluma.alice.ts.net on the old machine works on the new machine too, as long as the new machine reaches Pluma at the same tailnet URL and you've signed the device in to your tailnet.
What's safe to delete¶
models/<repo>/— re-downloadable from the HF browser.attachments/<name>.png— stale message attachments. The chat keeps the reference; the image just won't render.tsnet/— wipes the embedded Tailscale node. Re-enable from Settings → Privacy → Tailnet.- The entire
<datadir>— clean re-test of the first-run flow. You'll lose everything.
Per-conversation export¶
Export one chat as JSON:
curl -H "Authorization: Bearer $(cat ~/.config/pluma/cli.token)" \
http://localhost:8787/api/conversations/<id> \
> chat-<id>.json
The file is the decrypted form — re-encrypted on import via the standard PUT /api/conversations/{id} write path.
Character cards as portable artifacts¶
Tavern PNGs in <datadir>/characters/ are the share unit for characters — every edit re-embeds the JSON into the avatar. Copy a .png to another Pluma install and it just works.