Backup & Restore

Protect your KubeGraf data. Back up automatically, restore from any point, export to a new machine, and recover from laptop loss — all without your data ever leaving your control.

Local-first guarantee: All backup files stay on your machine. Nothing is uploaded anywhere unless you explicitly copy the file yourself. Exports are encrypted with your password — KubeGraf never sees it.

What gets backed up

KubeGraf stores everything in a single SQLite database at ~/.kubegraf/db.sqlite. The backup covers the entire database, including:

  • Cluster configurations and connection details
  • User accounts and authentication sessions
  • AI incident analyses, RCA reports, and conversation history
  • Confirmed fix patterns (incident service memory)
  • Event monitoring data and log errors
  • Application settings, notification preferences, and integrations
  • Cloud credentials, API keys, and tokens (all encrypted at rest)

Automatic backups

KubeGraf automatically backs up the database every hour to ~/.kubegraf/backups/. Backups older than 7 days are cleaned up automatically. At hourly intervals, you keep up to 168 snapshots — 24 per day.

Change the backup interval

  1. Open Settings

    In the KubeGraf web dashboard, click the gear icon in the header or navigate to Settings → Database Backup.

  2. Edit the interval

    Click the pencil icon next to the current interval value. Enter a new value in minutes (minimum 5, maximum 1440 = 24 hours).

  3. Save

    Click the checkmark. The new schedule takes effect immediately.

Manual backup

To create an on-demand backup at any time:

  1. Go to Settings → Database Backup

    Make sure automatic backups are enabled (toggle is on).

  2. Click "Create Backup Now"

    A timestamped .db file is created in ~/.kubegraf/backups/ immediately.

The backup list below the button updates automatically to show the new file.

Restore from a local backup

⚠️ Warning: Restoring overwrites your current database entirely. All data created after the backup was taken will be lost. This cannot be undone.

  1. Go to Settings → Database Backup

    Scroll down to the "Available Backups" list.

  2. Click "Restore" on the backup you want

    Backups are shown with their timestamp and file size. Choose the most recent one before the issue occurred.

  3. Confirm in the dialog

    Read the warning and click "Confirm Restore". KubeGraf will restore the database and reload.

Encrypted export — moving to a new machine

The standard local backups use the machine's encryption key — they cannot be opened on a different machine. Use Export to create a portable .kgbak file protected by a password you choose. This file can be safely stored anywhere and imported on any machine running KubeGraf.

Export your database

  1. Go to Settings → Database Backup → Export / Import

    Scroll past the automatic backup section.

  2. Enter a strong password

    This password encrypts the file. Choose something you will remember — it cannot be recovered if lost.

  3. Click "Export .kgbak"

    Your browser downloads a file named kubegraf-export-YYYYMMDD-HHMMSS.kgbak.

  4. Store the file and password safely

    Copy the file to an external drive, cloud storage, or another safe location. The file is worthless without the password — together they are everything needed to restore.

Encryption details: Exports use AES-256-GCM with a key derived via PBKDF2-SHA256 (600 000 iterations). The machine-specific key is not involved — only your password is required to decrypt on a new machine.

Import on a new machine

  1. Install KubeGraf on the new machine

    Follow the Installation guide. Run it at least once to initialize the database directory.

  2. Go to Settings → Database Backup → Export / Import
  3. Select your .kgbak file

    Click the file picker and choose the exported file.

  4. Enter the export password

    This must be the same password used when the file was exported.

  5. Click "Import Database" → Confirm

    KubeGraf decrypts the file, restores the database, and reloads. All your clusters, settings, and history are available on the new machine.

Common scenarios

Solved

Changing laptops

Export on old machine → copy .kgbak to new machine → Import. Done in under 2 minutes.

Solved

Database corrupted / SQLite crash

WAL mode protects against most crashes. If the database is corrupt, restore from the most recent automatic backup in ~/.kubegraf/backups/.

Solved

Accidental data deletion

Restore from a local backup taken before the deletion. Backups run every hour — worst case 1 hour of data loss.

Mitigated with export

Laptop lost or stolen

If you regularly export and store the .kgbak file off-device (external drive, personal cloud storage), you can restore on a new machine. Without an off-device export, the data is gone.

Best practice: Export your database monthly (or after major configuration changes) and store the .kgbak file somewhere other than your laptop — a USB drive, personal cloud storage, or another machine you own.

Backup retention

Automatic backups are retained for 7 days by default. Backups older than the retention window are deleted automatically after each new backup is created. At the default hourly interval this means you have up to 168 restore points at any time.

You can change the retention period in Settings → Database Backup → Retention Period. The range is 1–365 days. Increase it if you want a longer safety net; decrease it if disk space is a concern.

Manual backups created via "Create Backup Now" follow the same retention policy. If you want to keep a backup indefinitely, use Export to create a .kgbak file — exported files are never automatically deleted.

Troubleshooting

Backup directory not writable

If backups fail, check that ~/.kubegraf/backups/ exists and is writable:

ls -la ~/.kubegraf/
mkdir -p ~/.kubegraf/backups
chmod 700 ~/.kubegraf/backups

Import fails: "wrong password or corrupted file"

This means either the password is incorrect or the file was corrupted during transfer. Verify:

  • You are using the exact password entered when the export was created
  • The .kgbak file was not modified or partially transferred (check file size matches the original)

Import fails: "not a KubeGraf backup"

The file is not a valid .kgbak export. Make sure you are selecting a file exported from KubeGraf's "Export .kgbak" button, not a raw .db backup file. Raw .db files use the "Restore from Backup" path, not Import.

Restore fails: "integrity check failed"

The .db backup file is damaged. Try an earlier backup from the list — backups are timestamped so you can pick a known-good point.

Previous
Plugins
Next
Installation Issues