Upgrade notes

What an operator upgrading an existing deployment needs to know about recent schema migrations. New installations start from an empty database and can skip this page. The deployment order itself, and how to roll back, are in rolling deployment order and deployment reliability.

Before starting this release

Before starting this release, run alembic upgrade head through 0084_host_removal_move_out. The supported deployment scripts run migrations before replacing the API; every migration listed here is additive and safe under the running previous release unless it says otherwise. The few transitions that need stopped writers are listed in applying migrations that are not backwards-compatible.

After migrating, start the main control-plane listener with its existing complete environment: it imports newly registered settings once, as described in Admin Settings.

Recent migrations

Newest first.

Migration	What it changes
0084_host_removal_move_out	Adds agent_runner_hosts.removal_moves_out and removal_leaves_unmoved, false for every existing host, so a removal already pending keeps its earlier meaning: revoke once its running turns end.
0083_host_move_out	Adds the move_out purpose to the admission-hold check constraint. Changes no existing row. Its downgrade deletes any move-out holds; groups already moved keep their checkpoints.
0082_team_environments	Adds nullable team columns to environments and their bindings, and lets a repository default name any environment. Changes no existing row. Its downgrade refuses while a team environment exists, archived ones included.
0081_snapshot_pushed_commit	Adds agent_sandbox_snapshots.pushed_commit_sha and copies into it the commit of every snapshot that was never published. published_commit_sha is left as it was, so the API it replaces keeps working, and no notice fires.
0080_user_ssh_servers	Adds the owner SSH server tables; see SSH servers. Changes no existing row.
0079_teams	Adds teams: members, single-use invitations, join requests and the team audit log. Nothing else refers to a team yet, so it changes no existing row and nothing anyone can run or read.
0078_environment_snapshots	Adds environment installation snapshots and the setup fingerprint on environment bindings that decides which snapshot a workspace may start from; see environment installation snapshots.
0077_sandbox_usage_days	Adds the per-day container usage table and an owner index on agent_sandboxes, built without CONCURRENTLY. That table holds one row per retained container, so the brief write lock is short.
0076_mcp_residency_fence	Adds a nullable residency generation to MCP approval records; existing approvals keep it empty.
0075_runtime_upgrades	Adds two empty JSON columns for agent updates from the admin Settings page.
0074_host_removal_pending	Adds agent_runner_hosts.removal_requested_at, empty for every existing host. A downgrade drops it and leaves a host that was waiting to be removed draining.
0073_sandbox_restore	Adds the cold and restoring sandbox states and the start fence that binds a checkpoint to the run it ends; see restoring a removed host’s sandboxes. Existing checkpoints carry no fence and never move a group. Its downgrade refuses while any group is cold or restoring.
0072_drop_old_memory_tables	Drops the retired memory tables. A rollback to before 0070 finds them empty, without the earlier memory’s portraits and preferences.
0071_temporary_workspaces	Drops NOT NULL from agent_threads.repo and agent_environment_bindings.repo, so conversations can start without a repository. Its downgrade refuses while any such conversation exists.
0070_memory_cutover	Moves the memory switches and saved preferences onto the durable-memory table.
0069_agent_memories	Adds the durable-memory table.
0067_failed_snapshot_wake	Only replaces a trigger function.
0066_admin_job_listing_index	Builds an index on agent_jobs concurrently. On a long job history it takes a while without blocking the running API; an interrupted run can simply be repeated.
0051_host_drain_fence_epoch	Backfills a non-null drain-fence epoch for every host. The database rotates that epoch whenever drain-relevant lifecycle, credential, placement or ownership state changes. Once the V2 control plane is activated, this revision and the AGENT_DEPLOY_DRAIN_FENCE_V2 recipe marker are the application and schema rollback floor; see rollback compatibility.
0049_host_drain_fence	Starts every existing host without a deployment drain owner or release receipt. The V1 marker it introduced remains only so an older orchestrator can perform the bridge upgrade; it is not a rollback target after V2 activation.
0048_sandbox_plugins	Adds agent_threads.plugins; existing chats default to no plugins. Rebuild the sandbox image so the updated CLI wrappers load selected plugins.
0046_job_claim_retry	Adds agent_jobs.claim_retry_at, which the worker claim query requires. Existing queued jobs remain immediately eligible.

Older revisions that need a maintenance window are listed in applying migrations that are not backwards-compatible. A database still stamped with the retired pre-2026-09-10 chain cannot be upgraded directly; see preserving an old-chain database.

When you add a migration

Add a row to the table above in the same pull request, saying what an operator upgrading a live deployment needs to know: what existing rows it changes, how long it can lock, and whether its downgrade refuses. Then update the head revision named under Before starting this release and in ENVIRONMENT.md; a test checks that both name the current head.