Skip to content

DUMB API

The DUMB API is the central communication layer between the DUMB Frontend and the backend service. It handles requests for logs, service management (start/stop), configuration updates, and health checks.

At a glance

The dashboard and API clients share the frontend proxy. Direct native listener access is an advanced deployment choice.

flowchart TD
    A["Dashboard or API client"] --> B["Frontend proxy on port 3005"]
    B --> C["DUMB API authentication and capabilities"]
    C --> D["Managed services, configuration and logs"]
    D --> C
    C --> B

Access model

The maintained Compose file does not publish port 8000. The API binds to 127.0.0.1:8000 inside the DUMB container and dmbdb proxies it through the normal frontend address:

Use URL
REST through dmbdb http://<host>:3005/api/<backend-path>
WebSockets through dmbdb ws://<host>:3005/ws/<stream>
Native API inside the container http://127.0.0.1:8000/<backend-path>

For example, native /process/processes is exposed as /api/process/processes through dmbdb. WebSocket routes do not gain an /api prefix.

The proxy is available to more than the dashboard itself. Scripts, integrations, and other API clients can call http://<host>:3005/api/...; dmbdb removes the gateway prefix and forwards the request to FastAPI. The backend performs the same authentication and authorization checks regardless of which access path was used.

Direct exposure

Setting host to 0.0.0.0 and publishing port 8000 exposes powerful lifecycle and configuration endpoints. Enable DUMB authentication and restrict the port to trusted networks before doing this.


Development and release versions

Use the documentation channel that matches your installed DUMB backend. A development image can include a newer API version and features absent from the latest stable release; check Settings → About and the backend capability response before using them.

DUMB's dev branch records the version planned for the next stable release. The source/API version is a plain semantic version such as 2.24.0; a development image displays a rolling identity such as v2.24.0-dev.34 and the Dev build badge in Settings → About. The development suffix identifies the image build. API compatibility checks use the source/API core version and the backend's advertised capabilities.

The release manifest tracks the last actual stable release. For example, while the stable release is 2.23.0, development source can declare 2.24.0 with a manifest baseline of 2.23.0. Promoting that work through the normal master release process produces 2.24.0. Advancing the development source version does not consume that release number or create a stable tag.

Keeping the development version current

The Sync dev version workflow runs after a dev push, after publication of a stable release, and when manually requested. It calculates the next version from the actual stable release and subsequent commits using the pinned release-please calculator and repository release policy. When necessary, it commits only pyproject.toml and .github/.release-please-manifest.json back to dev. It keeps the manifest at the stable baseline and updates the source version to the candidate.

After 2.24.0 is released, the next development candidate is normally 2.24.1; a new feature can make it 2.25.0 under the release policy. Repeating synchronization with unchanged release history and commits makes no new commit. Its own version-update commit can trigger ordinary CI and another synchronization check, which makes no further change.

For maintainers:

  • Use Actions → Sync dev version → Run workflow, selecting dev. Enable Calculate the dev version without committing it for a preview-only run; leave it disabled to apply a needed metadata update. Check the workflow summary for the stable baseline, candidate API version and source SHA. Rerun after correcting an access or configuration failure.
  • The workflow uses the existing RELEASE_PLEASE_TOKEN. Its authenticated GitHub account supplies the commit identity. That token must be able to write repository contents on dev under the repository's branch rules; token-created commits allow the normal CI checks to run.
  • A concurrent change to the branch must not be overwritten. If the expected branch head changes before the update is accepted, rerun synchronization against the current head.
  • Synchronization updates source metadata. It does not create a release PR, stable tag, GitHub release, or container image. Image builds retain their manual and release-triggered entry points.

dmbdb uses the same synchronization approach with its own main release branch, package version and stable release history. Its candidate version is independent of the DUMB API version. See frontend development versions.

Manual dev image builds also calculate the API version once for the requested immutable DUMB commit, so both architecture builds use the same version even when synchronization has not yet landed. The build keeps that requested source SHA; it does not silently check out a newer dev commit. See building a development image for frontend selection and image digest checks.

Technical details: configuration reference

Configuration Settings in dumb_config.json

Located in dumb.api_service:

{
"enabled": true,
"process_name": "DUMB API",
"log_level": "INFO",
"host": "127.0.0.1",
"port": 8000
}

Configuration Key Descriptions

  • enabled – Whether the API service should run.
  • process_name – Used in process management and logs.
  • log_level – Logging verbosity for the API.
  • host – Address on which the backend listens. Keep the default loopback value when using dmbdb.

    0.0.0.0 allows access to the API from all addresses

  • port – Internal backend listener port. It is not automatically published to the Docker host.

What the API owns

  • Optional JWT authentication and user setup
  • Service lifecycle, dependency graphs, update controls, and onboarding
  • DUMB and service configuration validation/persistence
  • Logs, current metrics, metrics history, Database Health, and notifications
  • Symlink repair/snapshots and guarded SQLite-to-PostgreSQL migration jobs
  • Optional AI diagnostic bundle preview and provider calls
  • Real-time log, status, and metrics WebSockets

The backend advertises optional features through GET /process/capabilities. Frontends and automation should gate newer actions on these capability flags instead of assuming every DUMB version supports every endpoint.

Health and interactive schema

  • Native health check: GET /health
  • OpenAPI JSON: /openapi.json
  • Swagger UI: /docs
  • Scalar UI: /scalar

The interactive documentation endpoints live on the native backend listener. See the API overview for access choices and the complete reference.

Persistence and logs

API settings are stored with the main runtime configuration at /config/dumb_config.json. Authentication users and the generated JWT secret are stored separately at /config/users.json. DUMB logs are written below the configured /log directory.

When the backend exposes runtime_api_log_level, the DUMB API service page can temporarily enable DEBUG logging for the running DUMB and Uvicorn loggers. This requires no restart, does not modify dumb_config.json, and automatically returns to configured logging after the override is disabled or the container restarts. It does not change managed-service verbosity.