Backups & data
Cast snapshots each agent on a daily schedule. Knowing what those snapshots cover — and the data they don't — is the difference between a clean recovery and a surprise.
The unit of backup is the agent folder. Cast takes an automatic daily snapshot of each one; the agent's keypair and your server-level config need separate attention, covered below.
Automatic snapshots
Once a day, after a configurable UTC hour, Cast tars the agent's folder to <agent>/.backups/YYYY-MM-DD.tar.gz. New agents are created with this on. The archive holds everything in the folder except dot-directories (.backups/, .stamps/, and other scratch) — so blueprint/, config/, state/, memory/, home/, and secrets/ all travel.
At most one snapshot is kept per calendar day, and if nothing changed since the last one the new tarball is discarded (it's compared by content hash). A quiet day simply produces no file — that's expected, not a failure. Older snapshots are pruned once the count passes retain.
| Field | Type | Default | Effect |
|---|---|---|---|
| retain | int | 7 | Number of snapshots kept. Once exceeded, the oldest are deleted. |
| hour | int (0–23) | 3 | UTC hour at or after which the day’s snapshot is taken. |
{
"backup": { "retain": 7, "hour": 3 }
}What's covered, and what isn't
The snapshot is the agent folder, and nothing else. Everything that defines and records one agent is inside it; data that lives at the server level is not — back that up yourself.
| Location | In snapshots? | What it holds |
|---|---|---|
<agent>/ | Yes | Blueprint, config (model, ACL, extension credentials), state (conversation log, tasks, access grants, attachments), memory, home, and the keypair. The full breakdown is on Agent folder anatomy. |
~/.cast/config/ | No | Server-level data: routes.json, firewall.json, gateway.db, the identity database, and console/host logs. Not part of any agent snapshot. |
.env | No | Your Claude credentials. Lives in the working directory, never in an agent folder. |
To protect a whole install — not just one agent — copy ~/.cast/config/ and your .env alongside the per-agent snapshots. Paths are configurable; see Runtime options.
The agent's keypair
secrets/agent.key is the agent's Ed25519 identity key. It rides along in snapshots, but if you ever lose both the live folder and its snapshots, it's gone for good — there's no regeneration path that preserves the agent's identity. A replacement agent starts as a new identity, and its history won't be attributable to the old one. Treat this file as the one piece you cannot afford to lose.Restoring
There's no built-in restore command — recovery is a manual extract-and-copy. The archive contains the agent folder at its root, so extract it somewhere scratch, then copy the pieces you want back:
# stop the agent (or the whole server) first — see below
tar -xzf ~/.cast/agents/<name>/.backups/2026-05-27.tar.gz -C /tmp
cp -a /tmp/<name>/. ~/.cast/agents/<name>/Copy selectively if you only want part of it back — restoring blueprint/ to undo a bad edit, say, without rolling state/ back to a stale conversation log.
Backing up safely
The snapshot tars the agent's SQLite databases (state/agent.db and its -wal/-shm companions) while the agent may be mid-write. SQLite usually recovers a copy taken this way on next open, and the automatic daily snapshot accepts that small risk for unattended operation. For a backup you intend to rely on — and before any restore — stop the agent or the server first so the databases are quiescent and the copy is unambiguously consistent.