Backup and restore

ExportCopy Anchor Link

Platform admins can export local Nakama data from Control center → Workspace → Settings → Export ZIP.

The export is a .zip backup of the configured Nakama data root, which defaults to ~/.nakama and follows NAKAMA_CONFIG_DIR when set.

Treat export ZIPs as sensitive. They can include:

• Provider settings and API keys
• Auth data
• Org and profile workspaces (soul files, memory, artifacts)
• Org-level MEMORY.md, memory-archive/, and memory-history/ (see Org memory)
• Custom tools and skills
• Plugin packages and organization plugin data (snapshotted, not copied mid-write)
• The local SQLite database when it lives under the Nakama root

ImportCopy Anchor Link

Importing is a whole-install restore:

1. Preview the ZIP first
2. Confirm restore to replace the current local data root

The import accepts a ZIP up to 100 MB, up to 10,000 entries of 100 MB each, and up to 500 MB of uncompressed data. A larger archive is rejected before restore. Plan for downtime during restore because this replaces the active data root rather than merging individual records.

On a fresh install, you can also restore during First-time setup before creating a new admin account.

Restored plugins stay disabled until an organization admin enables them in Control center → Agent tools → Plugins. If a restored package no longer matches its stored hash, that release stays unavailable and must be installed again.

Profile packs (single agent)Copy Anchor Link

To move one profile without a full-root backup, open Agent, select the profile, and choose Export or Import. See Export and import an agent pack.

Those packs deliberately omit secrets and are not interchangeable with Export ZIP above.

Desktop dataCopy Anchor Link

Nakama Desktop uses ~/.nakama-desktop for server data instead of the normal ~/.nakama root. Its browser session lives in Electron's Nakama Desktop Electron app-data directory. The desktop app does not import an existing web server's ~/.nakama data, and restoring a normal Export ZIP doesn't automatically merge those stores.

To move Desktop server data, quit the app and copy the complete ~/.nakama-desktop directory. To restore it on another machine, place the copy at ~/.nakama-desktop before opening the app. Keep the browser session directory too when you want the saved login and window state. See Desktop for supported platforms and local-server behavior.

Desktop packaging and source builds are separate from backups. Build on macOS ARM64 or Windows x64. The macOS package targets macOS 15 or later on Apple Silicon; the Windows package targets Windows 10 build 19041 or later through the Microsoft Store. Cloud models still require internet access and provider credentials.

Docker volumesCopy Anchor Link

When Nakama runs in Docker, persist /nakama/data with a named volume or bind mount. Back up that volume (or use Export ZIP from the dashboard) before upgrades or migrations.

See Docker for volume setup.

Next stepsCopy Anchor Link

• Quickstart — install and first-run setup
• First-time setup — restore a backup during the setup wizard
• Docker — container deployment and volumes