# AutoKuma: Uptime Kuma monitors declared as Docker labels > AutoKuma is a Rust utility that creates Uptime Kuma monitors from Docker container labels, and can also read them from JSON and TOML files or from Kubernetes custom resources. It is aimed at teams running Uptime Kuma alongside a container workload who want monitors declared next to the service rather than clicked into a web UI. **BigBoot/AutoKuma** — AutoKuma is a utility that automates the creation of Uptime Kuma monitors based on Docker container labels. With AutoKuma, you can eliminate the need for manual monitor creation in the Uptime Kuma UI. - Repository: https://github.com/BigBoot/AutoKuma - Stars: 925 · Forks: 48 - Language: Rust - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/bigboot-autokuma ## The monitor belongs next to the container AutoKuma is described as a utility that automates the creation of Uptime Kuma monitors based on Docker container labels, and the README states the benefit plainly: with AutoKuma you can eliminate the need for manual monitor creation in the Uptime Kuma UI. That is the whole idea, and it is a small idea that removes a specific chore. Without it, every service you deploy needs a monitor created by hand in the Uptime Kuma web interface, with its URL, its type and its notification settings typed into a form. With it, the monitor definition travels with the service definition, in the same file, in the same commit, and it appears in Uptime Kuma when the container appears. The audience is therefore the team that already declares everything in Docker Compose or in Kubernetes manifests and is tired of a second, disconnected place where monitoring lives. The tool is not a monitoring system. Uptime Kuma does the monitoring, and AutoKuma is the reconciliation layer between your deployment description and Uptime Kuma's data. The project is organised as a Cargo workspace with four members, `autokuma`, `autokuma-playground`, `kuma-cli` and `kuma-client`, and the top level also carries an `ENTITY_TYPES.md` file, a `monitors/` directory, a `docs/` directory and two Dockerfiles. The workspace package metadata names Marco Kirchner of BigBoot as the author, with the MIT licence and edition 2021. ## The label grammar is four dots wide The label format is the contract between your deployment and the monitor, and it is small enough to hold in your head: ``` ...: ``` The prefix defaults to `kuma` and is configurable through `AUTOKUMA__DOCKER__LABEL_PREFIX`. The id is a unique identifier for the monitor, which is what makes several labels for the same service distinguishable, so `my-app` in the example below becomes the id of that monitor. The type is the monitor type, with `http`, `ping` and `dns` given as examples. The setting is the property to set. So a working pair of labels looks like this: ```yaml labels: kuma.my-app.http.name: "My App" kuma.my-app.http.url: "https://my-app.example.com" ``` The `name` and `url` settings are the properties of an HTTP monitor, and the id is shared between them. AutoKuma picks up the labels and creates the monitor in Uptime Kuma automatically. The grammar generalises to what Uptime Kuma can express, and the documentation covers the rest: groups, notifications, tags, templating, snippets, static monitors, and all the entity types. The groups and snippets features are worth understanding before you adopt the tool, because they decide how many labels you have to write. A snippet is a reusable piece of configuration that several monitors can share, and a group is a set of monitors with a common identity. Without them, every monitor needs its own set of labels for the same recurring settings, and the value of declaring monitors in code drops quickly. ## Compose, the Docker socket and a data volume The Quick Start section gives a Docker Compose file, and it is worth reading in full because the mounts carry the design: ```yaml version: '3' services: autokuma: image: ghcr.io/bigboot/autokuma:latest restart: unless-stopped environment: AUTOKUMA__KUMA__URL: http://uptime-kuma:3001 AUTOKUMA__KUMA__USERNAME: AUTOKUMA__KUMA__PASSWORD: volumes: - /var/run/docker.sock:/var/run/docker.sock - autokuma-data:/data volumes: autokuma-data: ``` Two things are happening. The container talks to the Docker daemon through the mounted socket, which is how it discovers the containers whose labels it needs to read. And there is a named volume at `/data`, which is where AutoKuma keeps its own state. That state volume is the part that deserves a second thought. AutoKuma has to remember which monitors it has already created, otherwise every restart would create a duplicate set of monitors in Uptime Kuma. Persisting that mapping in `/data` is what makes the reconciliation idempotent. The trade is that the volume has to be kept, and if it is lost the behaviour is not obviously graceful, because the tool can no longer tell a new container from one it has already seen. The environment variable naming is a nested configuration convention: `AUTOKUMA__KUMA__URL`, with double underscores separating levels. The minimum configuration is the same three variables, given separately: ```bash AUTOKUMA__KUMA__URL=http://localhost:3001 AUTOKUMA__KUMA__USERNAME= AUTOKUMA__KUMA__PASSWORD= ``` The configuration documentation covers the rest, including TLS, Docker host options, secret files and config file locations. ## Files, Swarm and Kubernetes, with an honest caveat The supported sources table is the part of the README that deserves the closest reading, because the statuses are not uniform. Docker is fully supported, with monitors sourced from container labels. Files is fully supported too, with monitors sourced from `.json` and `.toml` files. Docker Swarm is marked with a caveat, with monitors sourced from service and/or container labels. Kubernetes is also marked with a caveat, with monitors sourced from a custom resource, the CRDs being in `autokuma/kubernetes/crds-autokuma.yml`, and with the note that the Files and Docker provider might be used depending on your setup. The README then explains what the caveat means: these sources are supported on an as-is basis, as the author is currently not running any of them, and they are basically looking for a maintainer, with an invitation to get in contact if you would like to adopt one or add support for another source. That is a candid admission, and it changes how you should read the feature table. Docker and Files are exercised by someone running them daily. Swarm and Kubernetes are code that exists and has not been run against a real deployment by its author. The Files source deserves a second look from most teams, because it is the one that gives you version control. Monitors described in a `.toml` or `.json` file in your repository can be reviewed in a pull request, diffed, and rolled back, which is exactly the property that the Docker label approach trades away. The README's own documentation index lists a separate page for static monitors, which is presumably that path. ## kuma-cli and kuma-client cover the manual and the programmatic cases The same repository publishes two more tools, and they fill the gaps that label-driven automation leaves. Kuma CLI is a command-line tool for managing Uptime Kuma directly from the terminal. The command surface is a table of resources and their subcommands: `monitor` with add, delete, edit, list, get, pause and resume; `tag` with add, delete, edit, ls and get; `notification` with the same set; `maintenance` with add, delete, edit, ls, get, pause and resume; `status-page` with add, delete, edit, ls and get; and `docker-host` with add, delete, edit, ls, get and test. That last one is interesting, because `docker-host test` implies the CLI can verify a Docker host connection, and `maintenance` implies the CLI reaches into Uptime Kuma's maintenance windows, which is the feature you need when a planned outage should not page anyone. The install routes are three. Binaries for Windows, Linux and macOS are on GitHub Releases, there is a Snap package, and it can be installed with Cargo: ```bash sudo snap install kuma # or cargo install --git https://github.com/BigBoot/AutoKuma.git kuma-cli ``` The third tool is `kuma-client`, a Rust crate that provides a client library for interacting with the Uptime Kuma SocketIO API, with examples in the repository and documentation on docs.rs. That API detail explains the dependency list. The workspace pulls in `axum` 0.8 for the service itself, `bollard` 0.21 with the `aws-lc-rs` feature for Docker, `kube` 3.0.1 with `k8s-openapi` 0.27 for the Kubernetes source, `reqwest` 0.13.2, `clap` 4.5.21 with derive for the CLI, `config` 0.15.11 for the layered configuration, `postcard` for the stored state and `inkjet` for the JSON and YAML parsing. Having the client as a published crate means you can write your own reconciliation logic in Rust rather than accepting the one AutoKuma ships. ## The image is distroless and reports its own health The Dockerfile shows how the published container is built, and it is worth reading because two decisions there affect how you run it. ```dockerfile FROM rust:1.89 AS builder ARG FEATURES ARG TARGETARCH WORKDIR /usr/src/autokuma COPY . . RUN --mount=type=cache,target=/cache/$TARGETARCH,id=cache-ghcr.io/bigboot/autokuma-${FEATURES} \ cargo install --features "${FEATURES}" --locked --target-dir /cache/$TARGETARCH --path ./autokuma && \ cargo install --features "${FEATURES}" --locked --target-dir /cache/$TARGETARCH --path ./kuma-cli ``` The build is a two stage build on `rust:1.89`, installing both the `autokuma` binary and the `kuma` CLI with `--locked`, and using a BuildKit cache mount keyed on the target architecture and the feature set. The feature flag is a build argument, so the image can be built with a narrower feature set, and the cache key includes it so different feature builds do not evict each other. The runtime image is `gcr.io/distroless/cc-debian13:debug`, which contains no shell and no package manager, and only the two binaries are copied in. That is a good default for a container that reads a Docker socket: there is very little in the image for an attacker to use if they get code execution. Two runtime details matter for deployment. `ENV AUTOKUMA_DOCKER=1` tells the service that it is running inside Docker, which is presumably how it decides to read the local socket rather than requiring an explicit host configuration. And there is a health check: ```dockerfile HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \ CMD ["/busybox/wget", "-qO/dev/null", "http://localhost:8090/health"] ``` So the service exposes a health endpoint on port 8090, with a 30 second interval, a 5 second timeout, a 30 second start period and three retries. That is the endpoint to point your orchestrator's liveness and readiness checks at. ## MIT terms and a 2.1 line still in release candidates AutoKuma is released under the MIT License, with the LICENSE file at the top of the repository and the same licence declared in the workspace metadata. MIT is permissive with no copyleft obligation, which is the usual arrangement for a utility that reads your Docker socket and writes to your monitoring system. The release history tells you where the project is. The tags are v2.0.0 on 2025-11-12, v2.1.0-rc.1 on 2026-05-23 and v2.1.0-rc.2 on 2026-06-18, and the last push was on 2026-06-18, the same day as the newest release candidate. So the current line is a 2.1 release candidate rather than a final release. That matters if you are putting this in front of a production cluster: you are choosing between a stable 2.0.0 from seven months ago and a 2.1 release candidate that includes whatever changed in the 2.1 series, including the Kubernetes CRD support that the README flags as unmaintained. The repository also carries a `CHANGELOG.md`, a `release.toml` for the release tooling, a `.pre-release-hook` script, a `snap/` directory for the Snapcraft package and a `zensical.toml` for the documentation site, alongside the `docs/` folder. There is a documentation site at autokuma.bigboot.dev/dev and a Playground instance at autokuma-playground.bigboot.dev, which is a useful thing to point at when you want to see what a label set produces before wiring it into your own stack. The workspace version field reads `0.0.0`, with the real version stamped at release time by the release tooling, which is why the tags and the manifest differ. It is a convention that avoids churn in a multi-crate workspace, and it is one more reason to read the tag rather than the manifest when you are pinning a version. ## Conclusion Adopt AutoKuma if your services already run as containers and you want their Uptime Kuma monitors declared alongside the service definition, with the monitor created as soon as the container appears. Skip it if you want a checked-in, reviewable definition of every monitor, since the file source is the one that gives you that, and be careful with the Swarm and Kubernetes sources, which the README marks as supported on an as-is basis because no maintainer is running them. Verify first that AutoKuma can reach the Uptime Kuma instance over its SocketIO API and that the container can read the Docker socket, then confirm the label format your compose files produce matches the grammar. The licence field on the repository says MIT, the last push was on 2026-06-18, and the newest tag is v2.1.0-rc.2. ## FAQ ### What does AutoKuma do? It is a utility that automates the creation of Uptime Kuma monitors based on Docker container labels, so you can eliminate the need for manual monitor creation in the Uptime Kuma UI. It can also source monitors from JSON and TOML files, and from Docker Swarm labels or Kubernetes custom resources. ### What is the label format AutoKuma reads? Labels follow `...: `. The prefix defaults to `kuma` and is configurable via `AUTOKUMA__DOCKER__LABEL_PREFIX`, the id identifies the monitor, the type is the monitor type such as `http`, `ping` or `dns`, and the setting is the property to set. ### How do I run AutoKuma with Docker Compose? The README's quick start uses the image `ghcr.io/bigboot/autokuma:latest` with `AUTOKUMA__KUMA__URL`, `AUTOKUMA__KUMA__USERNAME` and `AUTOKUMA__KUMA__PASSWORD`, mounting `/var/run/docker.sock` so the tool can read container labels, and a named volume at `/data` for its state. ### Are the Docker Swarm and Kubernetes sources of AutoKuma reliable? The README marks them with a caveat and says they are supported on an as-is basis because the author is currently not running any of them, and that they are basically looking for a maintainer. Docker and Files are the sources with full support. ### What other tools does the AutoKuma project ship? Kuma CLI is a command-line tool for managing Uptime Kuma, covering monitor, tag, notification, maintenance, status-page and docker-host resources, installable from GitHub Releases, via Snap or with `cargo install --git https://github.com/BigBoot/AutoKuma.git kuma-cli`. There is also `kuma-client`, a Rust crate for the Uptime Kuma SocketIO API. ### What licence is AutoKuma released under? It is released under the MIT License, with a LICENSE file in the repository. The releases are v2.0.0 on 2025-11-12, v2.1.0-rc.1 on 2026-05-23 and v2.1.0-rc.2 on 2026-06-18, and the last push was on 2026-06-18. ## Sources - [BigBoot/AutoKuma on GitHub](https://github.com/BigBoot/AutoKuma) - [Issues](https://github.com/BigBoot/AutoKuma/issues) - [License: MIT](https://github.com/BigBoot/AutoKuma/blob/master/LICENSE) - [README](https://github.com/BigBoot/AutoKuma/blob/master/README.md) - [Releases](https://github.com/BigBoot/AutoKuma/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bigboot-autokuma