Bedrock Server Manager 4.0.0

Bedrock Server Manager 4.0.0 brings a major rebuild of the application core, live world backups and exports, a refreshed web interface, stronger plugin contracts, and much better visibility into application health and failures.

This changelog consolidates the changes from 3.10.6 through 4.0.0b7, the latest published release tag at the time of preparation. It includes the improvements and fixes introduced throughout the 4.0 beta series.

Upgrading from 3.x requires attention: the Python/plugin APIs have breaking changes, the database schema is updated, service definitions may need regeneration, and the project license has changed.

Live world backups and exports

The active world can now be backed up or exported as a .mcworld file while its Bedrock server remains running.

Live exports use Bedrock's save hold, save query, and save resume workflow to capture the files reported by the server.
Save resumption is attempted during cleanup, including when export fails.
Export errors, timeouts, and failures to resume saving are reported.
Temporary archive files are cleaned up, and replacement exports use the updated file-handling path.
Backup and restore results distinguish completed, skipped, and failed components. Cleanup results distinguish deleted, retained, and failed items.

World, configuration, and combined backup scopes remain available. A combined backup covers the supported server backup categories; the BSM database, bootstrap configuration, and external plugins still need their own installation backup.

A rebuilt asynchronous core

Server management now uses asynchronous operations throughout much more of the application, including process control, installation and updates, world and add-on management, player scanning, access files, backups, authentication, settings, and database access.

Database access uses asynchronous SQLAlchemy sessions and the appropriate async drivers.
File and network operations use async implementations or explicitly delegated blocking work.
Per-server operation locks coordinate conflicting management actions.
Server software management, configuration, runtime state, and process operations have clearer component boundaries.
Background tasks, log streaming, and plugin execution follow the application's runtime ownership and cleanup rules.
The former mcstatus dependency has been removed.

These changes provide a more consistent foundation for concurrent management operations and orderly shutdown.

Validated state and more reliable persistence

Application records now live in a validated Pydantic v2 AppState, with persistent configuration separated from runtime observations such as process handles and live metrics.

Dedicated services own server, account, plugin, and settings mutations.
Storage coordinates change tracking, database transactions, and persistence.
Mutations validate their candidate data and commit database changes before publishing the updated in-memory record.
Serialized flushes, record locks, snapshot checks, and retry handling reduce conflicting writes and lost updates.
Returned state is copied so changing a result does not silently modify stored configuration.
Settings loading and reloads preserve stored values through corrected deep-merge behavior.
Supported startup automatically applies required database schema migrations.

This also addresses early 4.0 beta issues where database-backed settings could revert to defaults and web authentication could behave inconsistently.

Consistent state ordering over HTTP and WebSockets

Core HTTP snapshots and WebSocket updates now carry epoch and revision metadata so consumers can reconcile delayed responses and live events.

Revisioned data includes fleet/server summaries, running status, process information, task transitions, resource samples, and core event envelopes.
A task's HTTP snapshot and WebSocket update use the same stored revision for that transition.
Observation revisions are reserved before asynchronous work, so a slower earlier read does not become newer merely by finishing later.
A changed epoch identifies a backend restart and tells clients to refresh their ordering state.

Revisions order observations within a backend process. They do not make a fleet response an atomic database snapshot or synchronize multiple independent web workers.

Application Monitor and diagnostics

Application monitoring is now a core service, replacing the bundled benchmark plugin.

Authenticated clients can retrieve application metrics over HTTP or subscribe to live application-metrics updates.
Samples include application CPU and memory, host resource measurements, network and disk rates, event-loop delay, and background-operation information.
Recent metrics history is retained in memory; unavailable measurements are represented as unavailable rather than fabricated zero values.
Readiness and diagnostic health are reported separately.

Administrators also gain a broader diagnostics system:

Application summaries, subsystem observations, findings, and suggested actions.
Visibility into startup/shutdown phases, managed tasks, plugin resources, event delivery, storage contention, process monitoring, and transport failures.
Database-retained diagnostic history with filters, pagination, and correlation information.
Downloadable support reports containing version, platform, database, schema, and diagnostic metadata.
Snapshot comparisons that account for instance changes and counter resets.
Optional periodic diagnostic history collection.
Owned plugin diagnostic providers with bounded execution and cleanup.

Retained diagnostics use bounded, best-effort collection of sanitized metadata. They are a support history rather than a guaranteed audit log, and live metric history still resets on restart.

Refreshed web interface and appearance

The backend moves from the frontend 1.2 series to the 1.3 series, bringing the updated management interface and support for the new backend capabilities.

Refreshed branding, navigation, themes, and mobile layouts.
Expanded appearance controls, including light/dark/system modes, interface density, personal palettes, panorama backgrounds, and sidebar transparency.
Application monitoring and diagnostic views.
A dedicated plugin settings interface.
Corrected account-theme handling and broader panorama image support.
Read-only raw server-properties access for reference views.
Paged log history to complement live console streaming.

The backend package declares the compatible frontend dependency range. Install matching backend and frontend versions when deploying them separately.

Plugin settings with validation

Plugins now have dedicated database-backed settings storage, separate from global application settings.

Existing plugin settings are migrated into a dedicated plugin_settings table.
Plugins can declare a Pydantic settings_model to validate configuration and expose a JSON Schema to the settings interface.
Schema-driven forms support labels, help text, booleans, choices, numbers, and nested settings, with JSON editing for complex values.
Reads include declared defaults; writes validate complete settings objects.
Live server references and supported backup selections can be validated against the installation.
Bundled notification plugins use typed configuration.

The existing get_plugin_setting and set_plugin_setting helpers remain available. Changing a returned dictionary does not save it; plugins must explicitly write the updated value. Plugins that cache settings during loading may require a reload to apply edits.

Typed APIs and clearer operation results

Python API operations now use strict request and response models. HTTP routes have explicit, stable operation IDs and more consistent OpenAPI contracts.

Requests are validated before hooks or side effects.
Unknown fields, invalid types, and unsupported JSON values are rejected.
Results preserve meaningful completed, skipped, cancelled, and partial outcomes.
Infrastructure failures propagate as failures rather than misleading empty or successful responses.
Partial results can preserve work that committed before a later step failed.
Error classification and HTTP conversion are more consistent.
Malformed allowlist and permissions files are preserved for repair.
Player counts and player-scan results use consistent models and validation.
OpenAPI export, generated plugin API documentation, and internal caller checks have been standardized.

An accepted background task remains distinct from successful completion of its operation.

Application-owned events and plugin resources

The event system is now an application-owned subsystem, with scoped capabilities for plugins and WebSocket delivery handled as an observer.

Core before/after hooks carry typed request/result data with listener isolation.
Event IDs and correlation IDs connect related dispatches.
Plugin custom events have declared, validated payload contracts and explicit ownership.
Plugins can register public or private events, listener priorities, one-shot listeners, and filtered event waits.
Subscription tokens allow explicit unsubscription; owned subscriptions and event declarations are removed on unload.
Event activity and schemas are available through administrator endpoints.
Limits bound dispatch depth, capacity, listener timeouts, and synchronous workers.
Before-hook failures or timeouts can prevent mutation; notification failures after committed work are recorded without undoing it.
Plugin reload waits for owned work to drain, and stale capabilities cannot attach themselves to a replacement runtime.

Plugins can also broadcast WebSocket messages, send to a user, and register owned request/response data providers. Outgoing delivery is serialized per client through bounded queues, with delivery results that distinguish successful, unavailable, and failed recipients.

Graceful shutdown and safer hosting

A dedicated WebRuntime now coordinates web hosting and application cleanup.

Shutdown stops admission of new mutations, drains managed work, stops Bedrock servers, unloads plugins, drains events, closes WebSockets, flushes state, and closes database resources.
Administrators can inspect GET /api/runtime and request shutdown with POST /api/runtime/shutdown.
Shutdown returns HTTP 202 when accepted; cleanup completes afterward.
New API mutations receive HTTP 503 once shutdown admission closes.
Detached startup waits for readiness or startup failure.
Hosting uses process locks, atomic control records, and a per-instance shutdown credential.
Duplicate hosts using the same configuration directory are rejected.
CLI stop waits for graceful completion; forced termination is an explicit fallback with process-identity checks.
Systemd and Windows service behavior has been updated to follow runtime cleanup and report failures more accurately.

Run one application worker per configuration directory. Docker restart policies can restart a manager stopped through HTTP; stop the container when it should remain stopped.

Reverse proxies, HTTPS, and Home Assistant ingress

Forwarded HTTP and WebSocket information now follows one trusted-ingress policy.

web.forwarded_allow_ips controls trusted proxy sources; its default is 127.0.0.1.
Forwarded client addresses, HTTPS scheme, and ingress paths are processed only for trusted immediate peers.
Home Assistant and subpath gateways must strip the external prefix and provide X-Ingress-Path.
Runtime prefixes are applied consistently to frontend routes, API calls, WebSockets, and assets.
Session-cookie scheme and path handling follow the trusted external URL across setup, login, refresh, and logout.
CORS configuration now lives in database-backed web.cors_origins.
Legacy bootstrap CORS values are imported only when no database policy exists. Later edits belong in stored web settings and require a web-server restart.

Logging and reliability fixes

Standardized application logs and user-facing messages, with concise console output and diagnostic detail in file logs.
Corrected log filename collisions during reconfiguration.
Improved logging-handler ownership and recovery when file logging cannot be initialized.
Fixed settings reload/defaulting, account themes, and authentication issues encountered during the beta cycle.
Corrected player bans, player data handling, server installation paths, and shutdown behavior during the async migration.
Strengthened cancellation handling so cleanup finishes before cancellation propagates.
Expanded automated coverage for migrations, storage concurrency, copy isolation, API contracts, partial failures, events, plugin ownership, task lifecycles, graceful shutdown, proxies, and diagnostics.
Updated runtime dependencies and developer documentation, including generated contract references and migration guidance.

Breaking changes and compatibility

Area	Required change
Plugin/API calls	Await asynchronous operations and migrate to the current namespaced API. Flat calls, plural domain aliases, legacy `_api` names, and old async bridges are removed.
API arguments/results	Pass one request model or mapping and consume typed response models instead of assuming arbitrary keyword arguments and dictionaries.
Internal access	Replace direct plugin access to `app_context`, application state, or database internals with supported API and owned runtime capabilities. Caller identity is supplied by the bridge.
Event contracts	Update hooks for typed request/result payloads. Declare plugin-owned custom events before emitting them; core lifecycle and operation events are reserved.
Core integrations	Adapt code that imports former server mixins or depends on old server/context internals to the composed server and service boundaries.
Web process control	Web start/stop/process-status proxies have been removed from AppAPI. Use the supported CLI hosting commands or administrator runtime endpoints.
Database drivers	Retain the relevant database extra when upgrading. SQLite uses `aiosqlite`, MySQL/MariaDB use `aiomysql` for async access, and PostgreSQL uses `asyncpg`.
Service/proxy setup	Regenerate service definitions where needed and review shutdown allowances, restart policy, trusted proxies, ingress prefixes, and stored CORS origins.
License	The repository has changed from MIT to AGPL-3.0-or-later with the Bedrock Server Manager Plugin Exception. Review the release's LICENSE before redistribution or modification.

For example, a current plugin start operation is:

from bedrock_server_manager.api.models import StartServerRequest

result = await self.api.server.start(
    StartServerRequest(server_name="example")
)
self.logger.info(result.message)

Python 3.11 or newer remains required.

Upgrading from 3.10.6

Back up the installation. Preserve bootstrap configuration, the database, required data directories, worlds and server configuration, external plugins, and their settings.
Check integrations first. Update external plugins and API consumers for the 4.0 contracts, and remove any separately installed benchmark_plugin.py to avoid duplicate sampling.
Stop BSM gracefully. Confirm the manager and affected game-server processes have stopped before replacing the environment. For Docker, stop the container and account for its restart policy.
Upgrade the correct environment or image. Preserve configuration paths, persistent mounts, the database selection, and service-account permissions. Install the applicable database extra and compatible frontend package.
Update hosting configuration. Regenerate affected service definitions, allow enough time for shutdown, and verify trusted proxy, HTTPS, ingress, and CORS settings. Use one worker per configuration directory.
Start and inspect migration/startup logs. Verify accounts, server discovery, retained settings, plugin status, and application readiness before starting game servers.
Verify normal operation. Check login, live updates, server start/stop, task outcomes, backups and exports, plugin configuration, and shutdown through the deployment's normal access path. Sign in again after changing cookie or ingress configuration.

A package downgrade does not reverse database migrations or Bedrock world-format changes. Keep a compatible backup for rollback.

Release links

What's Changed

⚠️ Breaking Changes

Refactor!/move to async by @DMedina559 in #408
Refactor!/app state model by @DMedina559 in #415
Chore!/remove api suffix by @DMedina559 in #417
Release!/4.0.0b1 by @DMedina559 in #421
Refactor!/move api to pydantic by @DMedina559 in #431
Refactor!/bedrock server by @DMedina559 in #432

🚀 Features

Feat/live backups exports by @DMedina559 in #416
Feat/websocket access for plugins by @DMedina559 in #424
Feat/state revisions by @DMedina559 in #435
Feat/application monitor by @DMedina559 in #436
Feat/plugin settings storage by @DMedina559 in #437
feat: add persistent diagnostics and modular web composition by @DMedina559 in #444
Feat/local runtime readiness by @DMedina559 in #453

🐛 Bug Fixes

fix: prevent log filename collisions on reconfiguration by @DMedina559 in #440

📚 Documentation

refactor: standardize documentation and harden backend contracts by @DMedina559 in #443

💄 Style & Refactoring

Refactor/logging by @DMedina559 in #434
Refactor/api contract consistency by @DMedina559 in #439
refactor: extract application event subsystem by @DMedina559 in #441
refactor: own web runtime and graceful shutdown by @DMedina559 in #442

⬆️ Dependencies

dep: update mysqlclient requirement from <2.3,>=2.2.7 to >=2.2.7,<2.4 by @dependabot[bot] in #407
dep: update uvicorn requirement from <0.53,>=0.35.0 to >=0.35.0,<0.54 by @dependabot[bot] in #406
dep: update httpx2 requirement from <2.13,>=2.5.0 to >=2.5.0,<2.14 by @dependabot[bot] in #405
dep: update alembic requirement from <1.20,>=1.16 to >=1.16,<1.21 by @dependabot[bot] in #403
dep: update bsm-test-utils requirement from <0.2,>=0.1.0b2 to >=0.1.0b2,<1.1 by @dependabot[bot] in #409
dep: update types-aiofiles requirement from <24.2,>=24.1.0 to >=24.1.0,<25.2 by @dependabot[bot] in #410
dep: update sqlalchemy requirement from <2.1,>=2.0.0 to >=2.0.0,<2.2 by @dependabot[bot] in #419
dep: update pytest-mock requirement from <3.16,>=3.14.0 to >=3.14.0,<3.17 by @dependabot[bot] in #423
dep: update platformdirs requirement from <4.12,>=4.3.0 to >=4.3.0,<4.13 by @dependabot[bot] in #422
dep: update fastapi requirement from <0.142,>=0.115.0 to >=0.115.0,<0.143 by @dependabot[bot] in #427
dep: update asyncpg requirement from <0.32,>=0.31.0 to >=0.31.0,<0.33 by @dependabot[bot] in #433
dep: update mypy requirement from <2.4,>=1.10.0 to >=1.10.0,<2.5 by @dependabot[bot] in #428
dep: update black requirement from <26.6,>=25.1.0 to >=25.1.0,<26.11 by @dependabot[bot] in #430

Full Changelog: 3.10.6...4.0.0

DMedina559/bedrock-server-manager 4.0.0 on GitHub