Backup and Restore

What you'll accomplish: Create full or partial backups of your Hoziron platform state, list available backups, and restore from a backup archive.

What gets backed up

A full backup captures everything needed to reconstruct the platform:

An agents-only backup captures just the agent definitions, memory directories, and the memory database — useful for migrating agents between environments without overwriting platform config.

CLI usage

Create a backup

# Full platform backup (default location: ~/.hoziron/backups/)
hoziron backup create

# Agents-only (skip config, auth, audit)
hoziron backup create --agents-only

# Custom output path
hoziron backup create --output /mnt/nfs/hoziron-backup-2026-06-05.tar.gz

# JSON output for scripting
hoziron backup create --json

List backups

hoziron backup list

# Example output:
# ID                                     CREATED                SCOPE        SIZE
# a1b2c3d4-...                           2026-06-05 02:00:00    Full         12.4MB
# e5f6g7h8-...                           2026-06-04 02:00:00    Full         11.8MB

Restore from backup

Restore is destructive — it replaces the current platform state. The daemon should be stopped before restoring.

# Preview (no --confirm = dry run message)
hoziron backup restore /path/to/backup.tar.gz

# Actually restore
hoziron backup restore /path/to/backup.tar.gz --confirm

# Skip checksum validation (not recommended)
hoziron backup restore /path/to/backup.tar.gz --confirm --no-verify

After restoring, restart the daemon:

hoziron start

API usage

Create a backup

curl -X POST http://localhost:4200/v1/backup/create \
  -H "Content-Type: application/json" \
  -d '{"scope": "full"}'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/home/user/.hoziron/backups/hoziron-backup-20260605_020000.tar.gz",
  "scope": "full",
  "created_at": "2026-06-05T02:00:00Z",
  "checksum": "sha256:abcdef...",
  "size_bytes": 13012480
}

List backups

curl http://localhost:4200/v1/backup/list

Restore

curl -X POST http://localhost:4200/v1/backup/restore \
  -H "Content-Type: application/json" \
  -d '{"file": "/path/to/backup.tar.gz"}'

Backup archive format

Backups are standard .tar.gz archives containing:

hoziron-backup-20260605_020000.tar.gz
├── MANIFEST.json        # Metadata: id, timestamp, scope, version, file list
├── config.toml          # Platform configuration
├── .env                 # Environment secrets
├── keys.db             # Auth key store
├── audit.db            # Audit trail
└── data/
    ├── hoziron.db      # Memory substrate (SQLite)
    ├── agents/         # Agent manifests and state
    ├── memory/         # Memory layer files
    ├── workflows/      # Workflow definitions
    ├── schedules/      # Schedule definitions
    ├── competencies/   # Installed competencies
    ├── skills/         # Installed skills
    └── integrations/   # Integration configs

The MANIFEST.json records the Hoziron version that created the backup, enabling future version-aware restore logic.

Integrity validation

Each backup's SHA-256 checksum is computed at creation time. On restore, the checksum is validated by default (skip with --no-verify if needed). This detects corruption from storage or transfer issues.

Configuration

Optional [backup] section in config.toml:

[backup]
# Cron expression for automated backups (not yet active)
schedule = "0 2 * * *"

# Keep this many backups; oldest are pruned
retention = 7

# Custom storage path (default: $HOZIRON_HOME/backups/)
storage_path = "/mnt/backup/hoziron"

# Create a backup on graceful daemon shutdown (not yet active)
backup_on_shutdown = false

Operational recommendations

Frequency: Daily full backups for production. More frequent if agents process high-value data.

Retention: Keep at least 7 days of backups. For compliance environments, retain per your retention policy.

Storage: Store backups off-host. The archive is a standard tar.gz — copy it to NFS, S3, or any durable storage.

Pre-restore checklist:

1. Stop the daemon: hoziron stop
2. Verify backup integrity: the restore command does this automatically
3. Restore: hoziron backup restore <file> --confirm
4. Restart: hoziron start
5. Verify: hoziron health and hoziron doctor

Security note: Backup archives may contain secrets (.env, keys.db). Encrypt at rest if storing off-host. A future release will add built-in backup encryption.

Next steps

• Bare metal deployment — systemd service with backup cron
• Kubernetes deployment — CronJob for automated backups
• Security hardening
• Audit trail

Related:

• Docker Compose deployment
• Observability
• Troubleshooting recovery