:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Back up settings and sounds
The section is behind the posthog-desktop-settings-backup feature flag while it rolls out.
When the flag is off, the section and its search entry are hidden.
Open Settings → Advanced → Back up settings and sounds. Choose Settings and sounds or Sounds only, then select Export backup and choose where to save the JSON file. Copy the file to the other machine and use Import backup in the same section. Review the export version, the names of the settings the import writes, warnings, and sound previews, then select Import settings and sounds or Import sounds. When the backup carries custom instructions, the review shows the text that will replace yours, because the agent reads those instructions in every task. A backup with empty or missing custom instructions leaves the instructions on this machine unchanged. Canceling the file picker or the review leaves your settings unchanged.
Custom sounds are embedded in the file, including their names and audio, so you do not need to copy the original recordings separately. Both export options include the selected completion sound, volume, and the setting that scales playback with task length. Import keeps existing custom sounds, skips clips already imported, and preserves both clips when their IDs collide. It updates the selected sound to use the imported clip's new ID when needed. Settings missing from a backup keep their current values.
The full backup includes the portable preferences in the main settings store: task and model defaults, notifications, composer behavior, custom instructions, diff display, terminal appearance, and Advanced toggles, plus the theme. It excludes accounts and API keys, subscription connections, server-managed settings, workspace and repository paths, cached selections tied to a repository, system shortcuts, power settings, and onboarding history. It also excludes bypass-permissions mode and spend limits, since both are machine-local safety controls that normally require their own explicit confirmation; a backup file cannot enable bypass mode or clear a spend cap on the destination machine. Custom instruction file syncing stays configured on each machine; the files themselves are not included. A custom terminal font must also be installed on the destination machine. The backup is a readable JSON file and includes any text you put in custom instructions.
Backups record the exporting app version and a separate file format version. Import warns when the app versions differ, skips unavailable settings or unsupported values, and lists invalid sound entries. A missing or invalid selected clip leaves the destination's current sound selection unchanged. A newer file format requires an app update before import. Backups are limited to 64 MB; each custom sound retains the existing 1 MB and 5-second capture limits, with the same allowance for encoder rounding. A backup can contain at most 1,000 sound entries and 1,000 settings entries, so malformed files cannot produce an unbounded review list.
Maintaining the format
packages/core/src/settings/schemas.ts defines the explicit allowlist and validators for portable settings.
When a preference is added, changed, or removed, update this contract alongside its settings UI and persistence.
Unknown fields and invalid values are skipped individually; missing values are never replaced with defaults.
If a change cannot be represented compatibly, bump the file format version and add a migration before accepting it.
Keep app version metadata independent of the file format version.
The core service owns validation and merging, the UI supplies a store adapter, and Electron supplies native file dialogs and bounded file reads. Exports write to a temporary sibling file before replacing the destination. Export reads the current settings when you start it. Import merges the validated backup with the current sound library when you confirm it, then updates the settings and theme stores. The existing persistence code saves those changes in the same way as changes made with the settings controls. Import does not wait for a separate disk write before it reports success.
The UI reports each finished operation to analytics: Settings backup exported, Settings backup export failed, Settings backup imported, and Settings backup import failed.
The events carry the chosen scope, counts, and the error message the user saw. They carry no file path, setting value, or sound audio.
A closed file dialog reports nothing, because it is neither a success nor a failure.