# Hermes: a REST and push message broker sitting on top of Kafka

> Hermes is Allegro's Java message broker built on Kafka, and its contribution is a fault tolerant REST interface for publishing plus adaptive push to consumers. The README is mostly about development tooling, which tells you where the operational documentation actually lives.

**allegro/hermes** — Fast and reliable message broker built on top of Kafka.

- Repository: https://github.com/allegro/hermes
- Website: http://hermes.allegro.tech
- Stars: 872 · Forks: 221
- Language: Java
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/allegro-hermes

## Kafka underneath, HTTP and push on top

Hermes is described as an asynchronous message broker built on top of Kafka, and the README states the project's contribution in plain terms: a reliable, fault tolerant REST interface for message publishing, and adaptive push mechanisms for message sending.

That is the whole idea. Kafka already gives you a log and consumer groups, but every producer needs a client library, every consumer needs a matching one, and the two ends of a message have to be written in compatible code. Hermes inserts a service between them. Producers publish over HTTP, and Hermes forwards the messages into Kafka, then pushes them out to consumers in a way that adapts to how fast each consumer is reading.

The audience is a Java organisation that has decided Kafka is the right storage and delivery substrate but does not want every team in the company to embed a Kafka client. Allegro built it, and the repository carries the pl.allegro.tech.hermes.hermes-client artifact on Maven Central, so there is a published client for consumers as well.

The project pages are split across three places. The homepage is hermes.allegro.tech, the full documentation is on readthedocs under the hermes-pubsub project, and there is a ten minute getting started guide with Docker linked from the README. The documentation badge points at the latest published version of that readthedocs site, which is how you can tell whether the docs are tracking the code.

## The module map is the architecture

The repository root is a Gradle multi-project build, and the module names describe the system better than the README does.

There is hermes-api, which is the service side of the broker, hermes-client, the published client used by consumers, and hermes-common, the shared code. Then there is a set of components that describe a complete internal platform rather than a library: hermes-console and hermes-frontend for a user interface, hermes-management for administration, hermes-metrics for the metrics, and hermes-schema for the definitions of what a message looks like. hermes-mock is there for testing, hermes-test-helper for test fixtures, and hermes-benchmark for performance work.

Two module names point at the design of the delivery side. hermes-tracker is the component that records where a message is, and hermes-tracker-elasticsearch is its Elasticsearch-backed implementation, so message tracking is pluggable and the search backend is a separate module. That is consistent with the README's promise of fault tolerance and adaptive push, since a broker that tracks message state can decide to push, to retry or to hold a message for a consumer that is falling behind.

The rest of the root is the tooling around the build: build.gradle and settings.gradle for Gradle, gradlew and gradlew.bat for the wrapper, gradle.properties, config/ for configuration, docker/ for the container images, docs/ for the documentation sources, scripts/, an integration-tests/ directory, and a mkdocs.yml with a readthedocs.yml that builds the site. The requirements file pins the documentation toolchain to MkDocs 1.4.0 and the Material theme at 8.5.6, which tells you the docs are built with MkDocs.

## The README is a developer guide, not an operations guide

The most striking thing about this README is what it does not contain. There is no architecture description, no configuration reference, no list of REST endpoints, no deployment topology and no upgrade procedure. What it has instead is a note for users, a license section, and a development section covering code formatting and running the integration tests.

The note for users is itself a signal. It says the project is being reorganized and that the Issues tab has been disabled, with the instruction to use discussions from now on. So bug reports and questions go to GitHub discussions, and there is no issue tracker to search when the same question has been asked before. If you are evaluating the project, that changes where you look for a sense of how active the community is.

The operational answers are in the documentation site rather than in the repository. The getting started guide with Docker is linked from the README, the full documentation is on readthedocs, and the project page is at hermes.allegro.tech. The repository also holds RELEASE_FLOW.md, which is where the release process is described, and a docker/ directory for the images.

There is one more resource that is easy to miss and quite revealing: test reports are published at allegro.github.io/hermes/allure, and performance test results at allegro.github.io/hermes/performance. The existence of a published performance report page suggests the broker's throughput characteristics are tracked as part of the build rather than measured once by hand.

## Integration tests need a container runtime and a big enough VM

The integration and slow integration tests use Testcontainers, so they need a Docker-compatible runtime. On macOS with Podman the README asks you to export two variables before running any test that requires containers:

```bash
export DOCKER_HOST="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"
export TESTCONTAINERS_RYUK_DISABLED=true
```

The second one disables the Ryuk reaper container that Testcontainers normally starts to clean up after a run, which is what makes the setup work under Podman.

With that in place the tests run as usual through the Gradle wrapper:

```bash
./gradlew slowIntegrationTest
./gradlew integrationTest
```

The slow suite is the demanding one, because it spawns many containers concurrently. The README warns that the Podman VM should be configured with at least eight CPUs and ten gigabytes of memory, or container startup may fail unexpectedly:

```bash
podman machine stop
podman machine set --cpus 8 --memory 10240
podman machine start
```

That warning is a small but useful piece of engineering advice. A test run that dies during container startup is usually a resource problem rather than a code problem, and knowing the expected floor saves an afternoon of debugging the wrong layer. It also tells you something about the project: the integration suite stands up real infrastructure, Kafka included, so it verifies the broker against actual broker behaviour rather than against mocks. The hermes-mock module exists for the cases where that is not what you want.

## Formatting is checked by a script, so the fix is one command

Code style in this project is google-java-format, and the setup is described in enough detail to remove a common source of friction.

For IntelliJ, the README lists four steps: download the google-java-format plugin, set the custom VM options the plugin requires, enable google java-format in the settings, and enable Reformat code and Optimize imports for Java files under Tools, Actions on Save. With that in place each save triggers a reformat, so a contributor never has to think about style.

For everyone else, the check is a shell script in the repository, and the README explains how to get the formatter binary for macOS on Apple Silicon and for Linux on x86-64. The script is made executable and then run. If you would rather fix the whole project in one go than inspect the report, there is a second form of the same script:

```bash
./.github/scripts/check-google-java-format.sh --fix
```

The reason this matters for an evaluation is that it tells you how much of the contribution burden is automated. Format and import order are decided by a tool and verified by a script, so a pull request that fails on style is a matter of running one command. What is left for human review is the actual change.

The CI badge at the top of the README points at a workflow file at .github/workflows/ci.yml on the master branch, so formatting and tests are both enforced before a change lands. The repository carries a CONTRIBUTING.md for the rest of the process, and the topics list includes hacktoberfest, which means outside contributions are part of the plan rather than an accident.

## Apache 2.0 in the README, a custom licence in the listing

There is a discrepancy here that a careful reader should resolve before using the code.

The README states that hermes is published under the Apache License 2.0, with a link to the licence text. The repository listing, however, records the licence as other, described as a custom licence that GitHub cannot classify, with a pointer to the LICENSE file. Those two statements cannot both be the whole truth, so the LICENSE file in the repository root is the document to read, and the README line may simply be out of date.

That is worth doing properly, because a broker sits in the middle of a company's internal systems and the terms will be read by more than one team. The requirement is not legal advice, it is simply this: read LICENSE, and if it does not say what you expect, ask the maintainers in discussions, which the README designates as the place to bring questions.

On maintenance, the record is recent but not constant. The three most recent releases listed are hermes-2.21.3 on 2026-07-15, hermes-2.22.0 on 2026-08-07 and hermes-2.22.1 on 2026-08-18, and the last push was on 2026-10-22. The version numbering shows a long-running project with a patch release following a minor one within about two weeks, and the project page, the documentation links and the release flow file all point to a process that is formal rather than improvised.

The flip side of the same picture is the reorganisation. Issues are disabled, discussions are the channel, and the module layout may still be moving. That is the main risk to weigh in an adoption decision, and it is a process risk rather than a technical one.

## Conclusion

Adopt Hermes if your producers and consumers are not all able to speak the Kafka protocol directly, since the REST publishing interface and the adaptive push delivery are the parts you would otherwise write yourself. Do not adopt it if a plain Kafka client library already serves your topology, because Hermes adds a JVM service to operate, a second layer to debug during incidents and a project that is mid reorganisation with the Issues tab disabled. Before you deploy it, read the getting started guide on readthedocs, since the README does not contain installation steps, and check the LICENSE file yourself, because the README states Apache License 2.0 while the repository listing records a custom licence that GitHub cannot classify.

## FAQ

### What is the Hermes message broker?

Hermes is an asynchronous message broker built on top of Kafka. It provides a reliable, fault tolerant REST interface for publishing messages and adaptive push mechanisms for sending them, and it is written in Java.

### How do I run the Hermes integration tests on macOS?

The integration and slow integration tests use Testcontainers and need a Docker-compatible runtime. The README asks you to export DOCKER_HOST pointing at the Podman socket and set TESTCONTAINERS_RYUK_DISABLED=true, then run ./gradlew slowIntegrationTest or ./gradlew integrationTest, with the Podman VM configured for at least 8 CPUs and 10 GB of memory.

### Which licence applies to Hermes?

The README states that hermes is published under the Apache License 2.0, while the repository listing records a custom licence that GitHub cannot classify and points to the LICENSE file in the repository root. The LICENSE file is the authoritative document.

### Where is the Hermes documentation and how do I report a problem?

The full documentation is on readthedocs under the hermes-pubsub project, the project page is hermes.allegro.tech, and there is a ten minute getting started guide with Docker. The project is being reorganized and the Issues tab is disabled, so questions and reports go to GitHub discussions.

### Does the Hermes repository publish test and performance results?

Yes. The README links test reports at allegro.github.io/hermes/allure and performance test results at allegro.github.io/hermes/performance, and the build also contains a hermes-benchmark module.

## Sources

- [allegro/hermes on GitHub](https://github.com/allegro/hermes)
- [Issues](https://github.com/allegro/hermes/issues)
- [Project website](http://hermes.allegro.tech)
- [README](https://github.com/allegro/hermes/blob/master/README.md)
- [Releases](https://github.com/allegro/hermes/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/allegro-hermes