# Netflix Mantis for Java Realtime Applications

> Netflix Mantis is a Java platform for building realtime, operations-focused applications through jobs, stages, sources, sinks, and a control plane. Its Gradle workflow is documented, but the README does not provide a short application-launch tutorial.

**Netflix/mantis** — A platform that makes it easy for developers to build realtime, cost-effective, operations-focused applications

- Repository: https://github.com/Netflix/mantis
- Stars: 1,472 · Forks: 224
- Language: Java
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/netflix-mantis

## The job problem Mantis is designed to address

Mantis targets developers who need to build realtime applications while also managing execution across jobs and stages. The repository description calls these applications realtime, cost-effective, and operations-focused, but the source layout gives that claim a concrete Java structure. `mantis-runtime` contains the dependencies required by a job, its DSL, and communication with other jobs. Its example classes include `Source`, `Sink`, `KeyToKey`, and `GroupToGroup`. These names indicate that application logic is organized around data movement and transformations rather than only around a single request handler.

The intended audience is therefore more specific than ordinary Java application developers. A team needs a runtime and control plane capable of representing submitted jobs, their stages, worker execution, scheduling, and cross-job connections. `mantis-client` exposes operations such as `MantisClient::submitJob` and `MantisClient::killJob`, while `mantis-control-plane-server` includes `MasterMain`, `SchedulingService`, and `ServiceLifecycle`. This is a platform repository rather than a small library that can be understood from one class.

That distinction matters during evaluation. Mantis may fit a system that needs job-level coordination and distributed workers, but the repository README does not offer a complete minimal application, deployment sequence, or sample command that submits an observable source and sink. The repository includes `mantis-examples`, but the README does not document how to run one. The platform architecture can be evaluated, yet an adoption decision cannot rely on an undocumented quick-start path.

## Mantis job, stage, and worker architecture

The module table separates shared definitions, runtime behavior, communication, client access, and control-plane execution. `mantis-common` contains shared types such as `MantisJobDefinition`, `MachineDefinition`, and `MantisJobState`. `mantis-control-plane-core` holds common server code for the control plane server, client, worker, and agent. Examples in that layer include `TaskExecutorID`, `ClusterID`, `ExecuteStageRequest`, `JobAssignmentResult`, and `Status`. These class names indicate that stage requests and assignment results are first-class control-plane data.

The execution path visible in the repository is therefore a sequence rather than a single API call. An application uses the client-facing package in `mantis-client` to submit or kill a job. The control plane receives that request through components such as `mantis-control-plane-server`. Scheduling and stage execution are represented by `SchedulingService`, `ExecuteStageRequest`, and assignment-related types. Actual job code depends on `mantis-runtime`, where source, sink, and transformation abstractions live.

Inter-job behavior is separated again. `mantis-remote-observable` is described as the connection to other job and stage code and lists `RemoteObservable`, `ConnectToObservable`, and `ConnectToGroupedObservable`. `mantis-network` and publication modules exist, although the README leaves several of their purpose fields marked as TODO. That omission limits architectural confidence in those areas. The high-level separation is clear, but the README does not document wire formats, delivery semantics, retry behavior, ordering guarantees, or failure recovery for remote observables.

## Gradle, IntelliJ, and Docker setup for mantis developers

The README documents repository development rather than an application deployment. For an IntelliJ contributor or Java developer preparing the source tree, it directs developers to regenerate project and module files from `.baseline`. The generated project is described as preconfigured for Baseline code style and Checkstyle-IDEA support.

From a checkout, this command creates or refreshes the IntelliJ project files:

```bash
./gradlew idea
```

The README also says Docker must be installed and running to support local containers. It does not list an operating system matrix, Docker version, Java version, or container startup command, so those requirements cannot be inferred from the repository documentation.

A first compile verifies that the Gradle wrapper can configure and build the repository. The documented command is:

```bash
./gradlew clean build
```

The README does not describe what user-facing artifact or service appears after this completes, because this is a build operation rather than a first-use tutorial. It also does not provide a minimal command that starts `MasterMain`, submits a job, or displays a source-to-sink result. A prospective user should therefore treat a successful build as source preparation, not as proof that a local Mantis cluster is usable.

For contributors who only need the test task, the documented command is:

```bash
./gradlew clean test
```

The README states that releases run tests, integration tests, static analysis, Checkstyle, and the build, but it does not document how to invoke the integration tests separately.

## Local Maven publishing and Java formatting

Mantis provides two maintenance tasks that are directly relevant to repository contributors. Spotless is configured through a Gradle task that formats Java files. The documented command is:

```bash
./gradlew format
```

This is broader than a command for editing one file. The README says it autoformats all Java files, so a contributor using it should expect repository-wide formatting changes rather than a narrowly scoped edit.

The second task builds the deployment into the local Maven cache:

```bash
./gradlew clean publishNebulaPublicationToMavenLocal
```

That can support local consumption of a deployment without manually copying generated artifacts, although the README does not provide a Java dependency declaration, group ID, artifact ID, or version-selection example. The repository contains `gradle.properties`, `dependencies.lock`, and Maven-related publication tasks, but those details are not enough to construct a reliable external consumer configuration from the README alone.

The format and local-publication tasks demonstrate a Gradle-centered contributor workflow. They do not establish the upgrade path for an application already using Mantis. There is no documented compatibility matrix for Java, Gradle, Akka, reactive libraries, or connectors. There is also no migration guide in the README for breaking changes across the Java client, control-plane protocol, job definition, or worker versions. These omissions raise the cost of evaluating an upgrade beyond a single library whose dependency range can be inspected easily.

## Direct control-plane modules as an alternative integration path

The repository exposes a lower-level route that differs from the job-oriented `MantisClient` path. `mantis-control-plane-client` provides `MasterClientWrapper`, `MantisMasterGateway`, and `MantisMasterClientApi`, while `mantis-server-worker-client` provides `MetricsClient`, `MetricsClientImpl`, `WorkerConnection`, and `WorkerMetricsClient`. Based on the module descriptions, a direct control-plane or worker-client integration would interact with narrower APIs than submitting and killing whole jobs through `mantis-client`.

This is the clearest alternative visible in the repository itself. The job client models an application-level unit of work. The control-plane client models communication with the master, and the worker client models operational access to workers. Choosing between them is not a simple switch documented by Mantis, because the README does not state whether the lower-level interfaces are intended for application authors, internal connectors, or other platform modules.

The trade-off is concrete. A direct integration could avoid the conceptual overhead of a full job definition, but it also moves the caller closer to scheduling, worker, metrics, and execution details. The job-oriented interface is the clearer choice when application code should submit and terminate managed jobs. The lower-level modules deserve separate scrutiny when the integration itself must understand worker connections or control-plane state.

The README does not justify comparing Mantis with another named stream-processing platform because it supplies no facts about such a platform. It also does not document a REST API, CLI, or protocol compatibility guarantee. A technical evaluation would need examples from `mantis-examples` and the relevant client documentation before selecting either path.

## Operational boundaries in the repository documentation

The most visible weakness is the gap between platform scope and documented adoption instructions. Mantis presents a distributed system with a server, agent, worker, master client, runtime loader, autoscaler API, connectors, remote observables, and multiple publication modules. Yet the README focuses on contributor builds and does not explain how to configure a local cluster, choose a resource cluster, deploy workers, submit the first job, or inspect its status.

Several module descriptions are incomplete. `mantis-discovery-proto`, `mantis-network`, `mantis-publish-core`, `mantis-publish-netty`, and `mantis-publish-netty-guice` have purpose entries marked `todo: need to fill this in`. The documentation therefore cannot establish what guarantees or responsibilities those modules carry. This is especially relevant for an operations-focused platform, where network behavior and discovery are not peripheral details.

The available release history also needs separation from source maintenance. The repository is not archived, and its last push was on 2026-09-24. The newest listed release is `v1.3.52` from 2022-07-25, with earlier listed candidates from April 2022. A recent push does not by itself identify a deployable release, supported version, or release cadence.

Apache-2.0 is the repository license. That identifies the license under which the source is offered, but teams still need to review the actual `LICENSE` and `NOTICE` files for attribution, notice, and modification obligations relevant to their distribution. This is not legal advice. The engineering cost is easier to assess: contributors must account for a modular Java build, local publication, CI release checks, and the absence of a documented compatibility or upgrade matrix.

## What the v1.3.52 release process requires

The documented release mechanism is Git tagging. A tag named with the format below starts a CI build:

```text
vMajor.Minor.Patch
```

The README states that this build runs unit tests, integration tests, static analysis, Checkstyle, the build, and publication to a public Bintray repository for synchronization with Maven Central. Contributors may create the tag through Git or the GitHub Release interface. This describes the release path, but it does not identify required credentials, environment variables, branch policy, signing procedure, or recovery process.

That matters for an organization considering an internal fork. Repository contributors can follow the documented commands and tag format, but deployers need a more precise answer about artifact availability and supported versions. The listed Bintray publication path also deserves direct verification because the README does not state when that service configuration was last confirmed or whether the release process still uses it unchanged.

The release history offers concrete version identifiers, but not a migration story. `v1.3.52`, `v1.3.43-rc.58`, and `v1.3.43-rc.57` are listed, while no compatibility table appears in the README. Before changing an application from one Mantis version to another, inspect the build files and release notes for removed classes, changed APIs, or cross-module version alignment. Do this before treating a version bump as a routine dependency update.

## Conclusion

Adopt Mantis when a Java team specifically needs its job DSL, stage-oriented runtime, control plane, connectors, and distributed execution model. Do not choose it from the repository description alone if you need a documented quick-start deployment. Before adoption, verify the missing end-to-end launch instructions, current operational requirements, dependency compatibility, and the release process you would use. The first repository-specific acceptance step should be `./gradlew clean build` and `./gradlew clean test` on `master`.

## FAQ

### What is Netflix Mantis used for?

Netflix Mantis is a Java platform for building realtime, operations-focused applications. Its modules model jobs, stages, workers, scheduling, remote observables, sources, and sinks.

### How do I build Netflix Mantis from the repository?

The README documents `./gradlew clean build`. It also says Docker should be installed and running to support local containers.

### Does the Netflix Mantis README show how to run a first application?

No. The README documents contributor setup, builds, tests, formatting, local Maven publication, and releases, but it does not give a minimal application-launch or job-submission sequence.

### Which license applies to Netflix Mantis?

The repository identifies Apache-2.0 as its license. The `LICENSE` and `NOTICE` files in the repository are the sources for reviewing applicable obligations.

## Sources

- [Issues](https://github.com/Netflix/mantis/issues)
- [License: Apache-2.0](https://github.com/Netflix/mantis/blob/master/LICENSE)
- [Netflix/mantis on GitHub](https://github.com/Netflix/mantis)
- [README](https://github.com/Netflix/mantis/blob/master/README.md)
- [Releases](https://github.com/Netflix/mantis/releases)

---

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