Upgrading Trinity

Run the six-probe verification. All must pass before you declare the upgrade complete:

# 1. Backend
curl -s http://localhost:8000/health
# Expected: {"status":"healthy",...}

# 2. Scheduler
curl -s http://localhost:8001/health
# Expected: {"status":"healthy","active_schedules":N}

# 3. Frontend (HTTP 200)
curl -s -o /dev/null -w '%{http_code}' http://localhost
# Expected: 200

# 4. Redis
docker exec trinity-redis redis-cli ping
# Expected: PONG

# 5. MCP Server
curl -s http://localhost:8080/health
# Expected: 200 OK

# 6. Vector (log aggregation)
docker exec trinity-vector wget -q -O - http://localhost:8686/health
# Expected: non-empty response

curl -s http://localhost:8000/api/version
# Expected: {"version":"<version>","git_commit_short":"<sha>","git_branch":"...","build_date":"...","install_source":"..."}

Retention windows do not change on upgrade. Every install stores its retention windows (execution logs, health checks, soft-deleted agents, backups, …) as explicit per-install settings, written at the values already in force the first time a release boots without them. A new release therefore never widens or narrows what your instance keeps; change a window deliberately under Settings → Retention (see Monitoring).

Rebuild the base image only when docker/base-image/Dockerfile changes:

./scripts/deploy/build-base-image.sh

On a hosted install there is no separate step — start.sh --hosted pulls the release's base image and retags it as trinity-agent-base:latest on every run.

How agents pick it up. A rebuilt or re-pulled base image is adopted at an agent's next cold start— that is, the next time it goes from stopped to running. Trinity compares the running container's image against the current base image and recreates the container when they differ.

What this means in practice:

• A running agent is never replaced out from under you. Drift is detected but not acted on until the agent is next started cold.

• Restart the fleet (Operations) to roll the new image out: each agent goes through the normal lifecycle, so a drifted agent is recreated and an up-to-date one keeps its container.

• The system agent (trinity-system) follows the same rule and is deliberately never replaced while running. If its image goes stale you get an operator alert rather than a mid-operation container swap; it adopts the rebuild the next time it is started cold.

• Rebuilding the base image is what makes newly shipped agent-side features available. Skipping it means agents keep running the old runtime, which is usually harmless but occasionally leaves a feature silently inert.

Agent containers are now created with Docker's unless-stopped restart policy, so a host reboot brings them back. Agents created before that release still carry Docker's default (no) and stay Exited after a reboot until they are recreated. The create and recreate paths are fixed, so this population can only shrink — but an active fleet heals itself only as agents happen to be recreated. Run this once after upgrading rather than waiting:

# Census — which agents are still on `no`
for c in $(docker ps -a --format '{{.Names}}' | grep '^agent-'); do
  docker inspect -f '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' "$c"
done

# One-shot fix — changes the policy without starting a stopped agent
docker ps -a --format '{{.Names}}' | grep '^agent-' | while read -r c; do
  [ "$(docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' "$c")" = "no" ] &&
    docker update --restart unless-stopped "$c"
done

Use unless-stopped, never always: Trinity stops an agent through Docker's manual stop, which unless-stopped honours, so a quarantined or deliberately stopped agent stays down across a reboot. On the dev compose the backend, frontend and redis services adopt the same policy on the next docker compose up (which start.sh performs). Two consequences worth knowing: “restarting frequently” alerts for agents now fire (they never could before), and a docker compose down leaves every agent in a restart loop rather than merely orphaned — see Monitoring → Recovery Patterns. Full runbook: docs/migrations/AGENT_RESTART_POLICY_2026-09.md.