Migrations Overview

Overview

Migration guides in rousseau-agent cover three axes:

1. Version upgrades — moving between tagged releases.
2. Deployment mode changes — bare-metal to containerised, single-host to multi-host.
3. Provider or transport swaps — switching LLM backends or chat channels mid-project without losing conversation history.

Every migration guide follows the same structure so operators can skim to the section they need.

Guide structure

Each migration page contains, in order:

1. What changed — the concrete diff at the config / CLI / data-store level. Never a philosophical summary.
2. Config diff — a before/after YAML block. Copy-pastable.
3. Data-store compatibility — whether sessions.db opens as-is, requires a schema migration, or must be exported/reimported.
4. Downgrade path — the reverse recipe. Rousseau follows a "one release backward" downgrade promise; further back requires the sessions.db backup.
5. Verification — the commands that prove the migration succeeded (rousseau doctor, rousseau session list, rousseau version).

Available guides

Versioning discipline

Rousseau uses semver: MAJOR.MINOR.PATCH.

• PATCH — bug fixes, no config-file changes, no data-store schema changes.
• MINOR — new fields with sensible defaults, additive tables. Backwards-compatible with a PATCH release. Downgrade allowed.
• MAJOR — renamed fields, removed subcommands, or a data-store migration. Requires reading the migration guide.

Every release ships:

• Signed checksums (cosign verify-blob).
• CycloneDX SBOM (rousseau_<v>_sbom.cdx.json).
• SLSA-3 provenance (rousseau_<v>_provenance.intoto.jsonl).

Verify the signature before any upgrade — see Security for the trust root.

Change types you might encounter

Related pages

• Migrations: 0.4 → 0.5
• Migrations: 0.5 → 0.6
• Migrations: Container migration
• Migrations: Provider migration
• Best Practices: Disaster recovery
• Changelog