Codex Backup Recovery

Codex Backup Recovery

Back up reusable Agent capabilities without bundling authentication files or an entire home directory. Treat the snapshot as private because memories and workflows can still contain personal context.

Workflow

1. Confirm scope and destination

Explain that this covers the allowlist in [references/snapshot-contract.md](references/snapshot-contract.md), not applications, Keychain, OAuth sessions, runtimes, or full-disk data. Let the user choose a local or cloud-synced output directory.

Never add credentials, arbitrary home-directory paths, or a public upload step.

2. Create the snapshot

python3 scripts/backup_recovery.py create \
  --home "$HOME" \
  --output "$HOME/Backups/agent-workspace"

Report both the .tar.gz archive and its .sha256 sidecar. Do not say the backup is valid merely because the files exist.

3. Validate it

python3 scripts/backup_recovery.py check \
  --snapshot "$HOME/Backups/agent-workspace/agent-environment-YYYYMMDD-HHMMSS.tar.gz"

Require a readable archive, safe member paths, allowed file types, and a matching checksum when the sidecar is present. Spot-check that no auth.json, session, log, cache, database, or symlink appears.

4. Rehearse restoration

Restore is a dry run by default:

python3 scripts/backup_recovery.py restore \
  --snapshot "/path/to/agent-environment-YYYYMMDD-HHMMSS.tar.gz" \
  --home "/path/to/test-home"

Review the destination list. The dry run must not create the destination directory.

5. Apply only after explicit confirmation

python3 scripts/backup_recovery.py restore \
  --snapshot "/path/to/agent-environment-YYYYMMDD-HHMMSS.tar.gz" \
  --home "$HOME" \
  --apply

After applying, open a few restored SKILL.md files and rerun the snapshot check. Re-authentication and application installation remain separate manual steps.

Existing destination files are refused by default. If the reviewed plan is intentionally replacing an existing Agent environment, obtain separate confirmation and add --overwrite; never use it as a convenience fallback after a collision.

Safety boundaries

• Use the fixed allowlist; never turn this into an unrestricted home-directory archive.
• Do not add an include secrets option.
• Never publish a real snapshot, even when credential files are absent.
• Do not claim disaster recovery is complete until creation, checksum validation, dry run, and restored-file spot checks all pass.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: smwswk
• Source: smwswk/xiaoming-agent-skills
• License: MIT
• Homepage: https://smwswk.github.io/skill-store/

Install and usage instructions live in the source repository linked above.