Upgrade & Migration

How to upgrade TameFlare to a new version. TameFlare follows semantic versioning — minor versions add features, patch versions fix bugs. Breaking changes are documented in the Changelog.

Standard upgrade

# 1. Pull the latest code
git pull origin main
 
# 2. Install updated dependencies
pnpm install
 
# 3. Apply database schema changes (safe — only adds, never drops)
pnpm db:push
 
# 4. Rebuild the gateway (if Go code changed)
cd apps/gateway-v2 && go build -o gateway ./cmd/gateway && cd ../..
 
# 5. Restart services
# If using pnpm dev:
pnpm dev
 
# If using Docker Compose:
docker compose build && docker compose up -d
Tip
pnpm db:push is always safe to run. It compares your database schema against the Drizzle schema definition and applies only additive changes (new tables, new columns). It never drops tables or columns.

Version pinning

To pin to a specific version, use git tags:

git fetch --tags
git checkout v2.0.5    # Pin to a specific release
pnpm install
pnpm db:push

To return to the latest:

git checkout main
git pull
pnpm install
pnpm db:push

Breaking change checklist

When upgrading across minor versions, check for:

| Change type | How to detect | Action | |---|---|---| | New required env var | Check .env.example diff | Add to your .env.local | | Schema change | pnpm db:push output | Run pnpm db:push | | API response format change | Changelog entry | Update SDK clients or scripts | | Gateway binary change | Go source diff | Rebuild: go build ./cmd/gateway | | Policy DSL change | Changelog entry | Review existing policies for compatibility |

# Quick diff of env vars between versions
diff <(git show v2.0.4:apps/web/.env.example) <(git show v2.0.5:apps/web/.env.example)

Migration from v1 (SDK-only) to v2 (proxy)

If you were using TameFlare v1 (SDK advisory mode only), v2 adds the proxy gateway. Your existing setup continues to work — v2 is backward-compatible.

What changes

| Component | v1 | v2 | |---|---|---| | Enforcement | SDK calls (voluntary) | Proxy interception (structural) + SDK | | Agent credentials | Agent holds API keys | Gateway holds API keys (credential vault) | | Gateway | Not required | Required for proxy mode | | Policies | YAML via API | YAML + access rules via dashboard | | CLI | tf status, tf agents | + tf init, tf run, tf connector, tf permissions |

Migration steps

  1. Keep existing setup running — v1 SDK mode continues to work in v2
  2. Set up the gateway: npx tf init or use the dashboard wizard
  3. Move credentials to the gateway: npx tf connector add github --token-env GITHUB_TOKEN
  4. Set permissions: npx tf permissions set --gateway "Bot" --connector github --action "github.*" --decision allow
  5. Switch agent to proxy mode: npx tf run --name "Bot" python my_agent.py
  6. Remove SDK calls from agent code (optional — SDK mode still works alongside proxy)
Note
You can run both modes simultaneously. Some agents use proxy mode (Mode A), others use SDK mode (Mode B). Both share the same policies, audit log, and dashboard.

Docker Compose upgrades

# Pull latest images
docker compose pull
 
# Rebuild custom images
docker compose build
 
# Apply schema changes
docker compose run --rm web pnpm db:push
 
# Restart with new images
docker compose up -d

Rollback

If an upgrade causes issues:

# 1. Stop services
# 2. Check out the previous version
git checkout v2.0.4
 
# 3. Reinstall dependencies
pnpm install
 
# 4. Restore database backup (if schema changed)
cp backups/local-pre-upgrade.db apps/web/local.db
 
# 5. Restart
pnpm dev
Warning
If pnpm db:push added new columns, rolling back the code without restoring the database is usually safe — Drizzle ignores unknown columns. But if you need a clean rollback, restore from backup.

Next steps