Backups
3 min read
Backups protect each agent's persistent volume: its working directory and files it created or received. Use them to recover an agent after an infrastructure incident, accidental deletion, or a failed change.
The destination is yours
Kujira stores backups in an S3 or compatible bucket owned by your organization. Configure it once in Settings > Backups. When saving it, Kujira checks that the credential can write and delete a test object.
Without a destination, there are no backups
Until a valid destination exists, neither manual nor scheduled backups can run. If you remove it, Kujira stops creating backups and cannot restore existing ones from the application, even though files remain in your bucket.
Define the strategy
The organization can set a default frequency and retention period. Each agent can inherit them, disable scheduled backups, or use its own schedule in Configuration > System.
- Scheduled backups protect work continuously. Retention keeps the last N scheduled backups for each agent and removes older ones.
- Manual backups create a recovery point before a sensitive operation. They are not included in automatic scheduled-backup cleanup.
Schedules are interpreted in UTC and may start a few minutes after the requested time.
Consistent backups
An agent can be writing while backup begins. Freeze container briefly stops activity during packaging to obtain a consistent volume state. It is useful before a critical restore or when the agent changes many files.
The trade-off is temporary unavailability and open connections may expire. Leave it disabled for ordinary backups unless you need that additional consistency.
Check the result
The global Backups list collects every agent's backups with origin, size, date, and status.
| Status | Meaning |
|---|---|
| Pending | The request is registered and waiting for the server. |
| Uploading | The agent is packaging or sending the volume to the bucket. |
| Completed | The backup is available to restore. |
| Failed | It could not complete; check the error and destination access. |
Kujira can also check that the object remains in the bucket. If it was deleted outside the app, it is marked missing rather than shown as recoverable.
Restore carefully
Restoring applies a backup over the agent's current volume. It replaces current files and is destructive. Kujira stops the container, restores content, and starts it again if it was running.
Before restoring, identify the right backup by date and size. Create a manual backup first if you need to preserve current state. Only completed backups still available at their original destination can be restored.
What a backup covers
It includes the agent's persistent /home content: workspace, created files, configuration, and other data inside its container.
Data that is not restored
Conversations, channels, memories, permissions, and organization configuration are managed by the platform. They do not depend on this volume and are not recovered by restoring an agent backup.
Permissions
| Action | Permission |
|---|---|
| View backups, their status, and availability | backup.view |
| Configure destination, create, restore, or delete a backup | backup.manage |