---
title: "Backups & export"
description: "Your assistant's memory, config, and credentials live inside its private virtual machine. HolaClaw can snapshot all of it to a backup on your Mac, take backups automatically, and restore one if something goes wrong."
updated: 2026-06-22
canonical: https://holaclaw.ai/docs/configuration/backups
---

Everything that makes your assistant *yours* — its configuration, the API keys
and logins it uses, its chat sessions, and its workspace — lives inside the
private virtual machine (VM) HolaClaw runs on your Mac. A **backup** is a
single snapshot of that state, stored as a file on your Mac, that you can keep
or restore later.

HolaClaw takes backups automatically, and you can also take one yourself at any
time from the assistant's **Backups** view.

## What's in a backup

A backup captures your assistant's state at a moment in time. You choose how
much to include with the **scope**:

- **Everything** *(the default)* — the OpenClaw configuration, the credentials
  and API keys, your chat sessions, and the workspace. This is a full snapshot
  you can restore to get the assistant back exactly as it was.
- **Config only** — just the active OpenClaw configuration file. Credentials,
  sessions, and the workspace are left out. Handy for keeping a small record of
  how the assistant is set up without copying its data.

Whether to keep the **workspace** (usually the largest part of a backup) and
whether to keep **only the config** are independent choices — a future release
will let you skip the workspace while still backing up everything else. Today
the two options above are the ones you can pick.

> **Note**
> A backup never leaves your Mac. HolaClaw has no servers in this loop — your
> backups, like your assistant, stay local.

## Where backups live on your Mac

Backups are stored **per assistant**, next to that assistant's VM state, under:

```text
~/.local/share/holaclaw/vf-vms/<vm-name>/backups/
```

Inside that folder you'll find:

- **`index.json`** — the catalog of backups for this assistant: one record per
  snapshot, with its id, name, scope, size, when it was taken, and whether it
  was a manual or automatic backup. The Backups view reads this file to show
  your list.
- **`<id>.tar.gz`** — the snapshot archives themselves. Each backup is a single
  gzip-compressed tar archive named after its id. This is the file that holds
  the actual captured state.

You normally don't need to touch these files — manage backups from the app —
but knowing the layout helps if you ever want to copy a backup archive
somewhere safe yourself.

## Automatic backups

By default, HolaClaw takes a **daily** automatic backup of each running
assistant and keeps the most recent few, pruning older automatic backups beyond
the retention limit so they don't pile up. Manual backups you take yourself are
**never** pruned automatically — they're kept until you delete them.

Automatic backups run from a background service that follows each assistant's
VM, so they keep happening whether or not the desktop app is open. You can
change the frequency (including turning automatic backups off) and the
retention count per assistant in its backup settings.

## Restoring a backup

HolaClaw **orchestrates the restore from your Mac (the host)** rather than
asking the assistant to restore itself. When you restore a backup, HolaClaw:

1. Stops the assistant and **moves its current live state aside** (it isn't
   deleted yet).
2. Loads the snapshot archive onto the VM.
3. Installs the OpenClaw version the snapshot was taken with, if it differs from
   the one running now.
4. Extracts the snapshot over the live state and starts the assistant back up.
5. Waits for the assistant to come back and checks that it's healthy.

If every step succeeds, the restore is complete and the moved-aside copy is
cleaned up. **If anything goes wrong** — the archive won't extract, the
assistant doesn't come back healthy, or any other step fails — HolaClaw
**rolls back**: it puts the moved-aside state back exactly as it was, so a
failed restore never leaves your assistant in a half-restored state. It also
keeps the logs from the attempt so you can see why it failed (and download them
from the restore dialog).