Backup and moving machines

Export

Project settings → Export backup…, set a passphrase (at least 8 characters), and you get a single .zip.

The passphrase protects the machine-local data that cannot travel in the clear; it does not encrypt the archive as a whole. Your project files are inside it as ordinary zip entries, readable by anyone holding the file — so store and send it the way you would treat the project folder itself.

What travels

The AI-POS management layer, not a copy of your repository:

• The parts of .aipos/ that define the project — configuration, module switches, workflow state, the event ledger, handoff snapshots, and pending or received delivery envelopes.
• tasks/, including each task’s artifact bundle (tasks/T-XXXX/), and work_record/ (the monthly work-report folder initialisation seeds with a _TEMPLATE.md).
• specs/ — the curated current-state spec layer, including the specs already folded in from finished tasks.
• The handoff layer: AGENTS.md, its CLAUDE.md import shell, project.yaml, aipos_docs/, memory/, and the workspace skills.
• artifacts/ only if you tick “Include artifacts/” — that box is off by default.

What does not

• Ordinary working files in the project root: your source code, your README, anything git already tracks. Move the folder itself, or let git move it.
• Machine-local files: .aipos/secrets.enc and the rebuildable search index.
• Which hub tools you have authorised (.aipos/agent_access.json). A restored workspace starts at the default again: agents can read, and every write tool is off until you allow it. See the checklist below.
• .aipos/asset_backups/ — the local safety net holding pre-upgrade copies of shipped files. It is deliberately left behind; it protects the machine it was made on.
• The root .mcp.json, the pointer that lets an agent CLI find the hub. It is written fresh per machine.

Restore

On the other machine: Projects → Import backup → pick the zip, pick a destination folder, enter the passphrase. The destination must not already be an AI-POS workspace, and a wrong passphrase aborts before anything is written.

Two things are worth checking straight after a restore:

1. Re-authorise the hub tools. This one is silent: the restored workspace starts from the defaults again — agents can read, but every write tool is off until you enable it on the Tools page. Until you do, refused writes look like the agent misbehaving rather than a permission that did not travel.
2. Glance at the hub connection. Import rewires the root .mcp.json for this machine automatically, so an agent CLI started in that folder finds the hub straight away. Only if the health card on the Tools page reports a problem — the bundled hub binary could not be resolved on this machine — press Repair connection.