Upgrade and recovery

These instructions cover v1.4.0 and current source changes explicitly identified in the release notes. Keep the previous executable and a matching backup.

Before upgrading

1. Stop MCPBox and confirm the process exited; never run two versions against one database.
2. Back up the entire installation/data directory, including hidden files, SQLite and any WAL/SHM files, package_store/, knowledge_base/, skill_store/ and .mcpboxpro/. Back up database and Skills files together.
3. Back up externally configured source directories, PostgreSQL/RagBox data, environment/secrets and proxy settings with the appropriate tools.
4. Verify the downloaded binary against the same release's SHA256SUMS.

Replace and verify

Replace only the executable, preserve data and configuration, then start it. Startup runs additive database migrations. Check login, project counts, enabled servers, CLI links, knowledge search, Skills bindings and job files. Test a harmless real MCP tool call, not only /healthz.

Both listeners now default to localhost: admin 127.0.0.1:38181, MCP 127.0.0.1:38182. v1.3.0 used 0.0.0.0 for MCP. For direct remote access, configure the bind explicitly with HTTPS/authentication; a same-machine tunnel needs no public bind. Old installations retaining admin 38180 must set MCPBOX_PORT=38180 explicitly.

PolicyBox migration

v1.4.0 removes that integration. Legacy identity-verification projects remain blocked until an administrator migrates them to bearer and pauses them for access review. Review retained OAuth clients before resuming. The new bearer does not reproduce PolicyBox's identity/role rules. Follow the migration guide.

Older editions and Skills

Former MCPBoxPro features are included without a license. Existing accounts and /api/pro/*, pro:*, MCPBOX_PRO_* compatibility names remain. Separate MCPBox/MCPBoxPro databases are not automatically merged. Existing SkillBox data is not migrated or deleted: import portable packages explicitly.

Rollback

Stop the new version. Restore the old executable and its matching pre-upgrade database, files, external state and configuration. Test restoration separately before production use; replacing only the binary does not reverse schema/data changes.