Update

Codifix v2.1.0 is the current stable release. It is a breaking major upgrade from v1: PostgreSQL data migrates in place and old bundles still import, but direct API clients, configuration, and renamed CLI commands need review.

Read the v2.1.0 release notes before upgrading a production installation.

1. Back up and inspect

Stop if either diagnostic already reports a database or authentication problem:

codifix --version
codifix status --project <project-slug>
codifix doctor
codifix health

Back up PostgreSQL before starting the v2 binary:

pg_dump "$DATABASE_URL" > codifix-before-v2.sql

If DATABASE_URL is stored only in codifix.env, load it through your normal secret-management workflow rather than copying it into shell history. For a portable memory-level backup, also export important projects:

codifix bundle export --project <project-slug> --out <project-slug>-before-v2.mlbundle.zip

2. Review the v2 breaks

Delete capnp_unix_socket and capnp_tcp_addr; the TUI and clients now use the /ws WebSocket stream.
Replace memory automation flush with codifix watcher flush, codifix capture task with codifix capture, and codifix dev init with codifix dev. Use codifix wizard instead of the removed memory setup.
Update direct HTTP integrations from the running service's GET /v1/openapi.yaml. v2 removed /v1/stats, /v1/offline/pending, and the browser auth-token handoff, and consolidated loop/activity routes.
Treat [writer], --writer-id, and CODIFIX_WRITER_ID as advisory labels. The authenticated principal supplies durable authorship.
Expect new bundle exports to use deterministic schema v2. Existing schema v1 bundles remain importable.

3. Install v2.1.0

Choose the command for the way you installed Codifix.

Debian or Ubuntu

Download the matching v2.1.0 .deb and checksum from GitHub Releases, verify the checksum, then install it:

sha256sum -c codifix_2.1.0_amd64.deb.sha256
sudo dpkg -i codifix_2.1.0_amd64.deb

Use the arm64 filenames on 64-bit ARM Linux.

Homebrew

brew update
brew upgrade 3vilM33pl3/codifix/codifix

macOS package or Windows MSI

Download the architecture-matched v2.1.0 installer and checksum. For a bundled Mac installation, choose the application-update package: it preserves the existing PostgreSQL/runtime tree. The standard package requires separately provisioned dependencies and refuses to overwrite a bundled runtime.

Windows is a preview. Use the exact -build.1 filenames in the release; the per-user installer uses %LOCALAPPDATA%\Programs\Codifix. Its separate server-tools MSI does not install the complete PostgreSQL/PDS/Pi stack. Signing and notarization status are stated in the release notes.

Source checkout

Check out the v2.1.0 tag, build with --locked, and follow the same service restart and verification steps as your original source installation.

4. Restart and migrate

codifix service restart
codifix doctor
codifix health
codifix status --project <project-slug>

The service embeds append-only migrations through 0084 and applies pending migrations at startup. Restart only the selected installation after reviewing its configuration and database. Named instances need their explicit upgrade procedure; package installation does not switch independently pinned releases. Do not run an older binary against the migrated database. Once new writes have been accepted, preserve them and recover forward rather than restoring stale state as authority.

Refresh repo-local Codifix skills only after reviewing the preview:

cd /path/to/project
codifix upgrade --dry-run
codifix upgrade

5. Verify integrations

codifix --version
codifix query --project <project-slug> --question "What changed recently?"
codifix resume --project <project-slug>
codifix watcher status --project <project-slug>
codifix mcp status

Direct API clients should fetch GET /v1/openapi.yaml from the upgraded service. MCP and agent clients should reconnect after the service restart so they negotiate the current tool surface.

Read Release compatibility and known limitations, Operations, or Doctor and health.