Backup & Restore

Anyy backup captures a coherent Profile snapshot. Restore always publishes into a new, nonexistent Profile directory; it never overlays live data.

Create a Backup

anyy backup create

The default archive is written under the Profile's backup area with a timestamped name. Choose another destination when needed:

anyy backup create --output /secure/path/anyy-backup.tar.gz

If the Gateway is reachable, the command asks the resident runtime to create the coherent snapshot. If it is offline, Anyy must acquire exclusive Profile ownership before reading mutable state.

What Is Included

The archive can include the Profile configuration, Role and Skill files, workspace and memory data, schedules, channel configuration, a database snapshot, and referenced durable objects or artifacts.

A backup captures one selected Profile; it does not bundle sibling Profiles or the installed Anyy executable. Back up each Profile separately.

Temporary runtime files are excluded. Symlinks are refused instead of following content outside the Profile.

Managed Credential Directories Are Opt-In

By default, backup omits the managed secrets/ and mcp/oauth/ directories. Add their Profile secrets and supported MCP/OAuth material explicitly:

anyy backup create --include-secrets

This flag controls those managed directories; it does not scan every included file for secrets. Configuration and user files are included with their contents: inline MCP environment/header values in config.yaml, or secrets in Workspace and other captured files, can enter the archive even without --include-secrets. Backup does not perform archive-wide redaction.

Protect every backup as sensitive data

Encrypt archives, restrict access, and do not upload them to ordinary file sharing or an issue tracker. Omitting managed credential directories does not guarantee a secret-free archive.

List Backups

anyy backup list
anyy backup list --json

The list command reports recognized archives in the Profile's backup location. An archive at a custom path can still be restored by specifying it directly.

Restore Safely

Choose a target directory that does not exist:

anyy backup restore \
  --archive /secure/path/anyy-backup.tar.gz \
  --target-home /path/to/new-profile

Before publishing the target, restore validates the manifest, file hashes, available space, paths, and archive structure. It stages the result beside the target, rebuilds required indices and audit state, then publishes atomically.

After restore:

anyy status --home /path/to/new-profile
anyy doctor --home /path/to/new-profile

Use the restored home explicitly for commands and the TUI:

anyy --home /path/to/new-profile
anyy dashboard --home /path/to/new-profile

There is no Profile import/register command. To restore as a named Profile, choose the not-yet-existing canonical target BASE_HOME/profiles/NAME, verify it, then run anyy --profile-root BASE_HOME profile use NAME. Do not run profile create NAME first: it creates the directory and restore will refuse it.

Recovery Rules

• Never choose the current Profile home as --target-home.
• Never restore over a directory that already exists.
• Keep the source archive until the restored Profile passes status and doctor.
• Reconnect omitted credentials before enabling outbound channels or paid providers.
• Test a restore periodically; an untested archive is only a backup attempt.

Troubleshooting

Symptom	Explanation
Backup refuses offline mode	A live process still owns the Profile; use the resident path or stop it
Restore says target exists	Pick a new empty path; overlay restore is intentionally unsupported
Hash or manifest validation fails	Do not bypass it; use another known-good archive
Restored providers cannot authenticate	The backup may have omitted managed credentials or rely on unavailable credential references; reconnect them