SoulFire: a Java Minecraft bot tool for server testing and automation

What SoulFire solves for Minecraft server operators

Testing a Minecraft server by hand is slow and hard to repeat. SoulFire is a bot tool that connects automated clients to a server so you can exercise join flows, load, plugins and world interaction without recruiting players. The README describes it as an advanced Minecraft bot tool for server testing, automation and development, and the feature list covers configurable session options such as the number of bots and join delay, saved profiles, online and offline mode servers, Microsoft and Offline accounts for Java and Bedrock Edition, and HTTP, SOCKS4 and SOCKS5 proxies.

The audience is narrow on purpose. This is for people who run or develop Minecraft servers and need programmatic clients. The README carries an explicit warning: use the tool only on servers you own or have permission to test, and make sure your hosting provider allows automated bot testing. If you are looking for a client to play on someone else's server, this is the wrong project, and the licence and the warning both push in the same direction.

One structural detail matters before you read further. This repository contains only the CLI and server implementation. The official GUI client lives in a separate repository, SoulFireClient. The README points to a hosted demo page if you want to see the interface before installing anything.

How SoulFire is put together: launchers, plugins and gRPC-Web SDKs

The repository layout tells you most of the architecture. There are two launcher modules, client-launcher and dedicated-launcher, plus a j8-launcher and a mod directory. A proto directory and a buf.yaml file sit at the top level, and the README confirms TypeScript and Python SDKs for connecting over gRPC-Web, streaming bot events, issuing per-bot actions and provisioning a local dedicated server. The package.json for the monorepo lists workspaces sdk/beat-game and sdk/typescript, with a sdk:generate script that runs buf generate and then a formatting script for generated SDKs.

So the shape is: a Java core that runs bot sessions, a launcher that starts either a GUI client or a dedicated server, and a protobuf-defined API surface that non-Java clients use over gRPC-Web. That last part is the interesting design choice. Instead of forcing every integration through Java, the project generates SDKs from proto definitions, which means the API contract lives in .proto files and the SDKs are build artifacts rather than hand-written wrappers.

The plugin side is less settled. The README states that SoulFire offers a Developer API for creating plugins using the plugin API and mixins, and then says plainly that SoulFire can include breaking changes, advising you to pin your plugin to a SoulFire version or update it when SoulFire changes. Mixins tie plugins to internal classes, so that warning is not boilerplate. Built-in plugins named in the README include AutoRespawn, AutoJump and ClientSettings. Pathfinding is listed as A* with diagonal moves, parkour, mining blocks and placing blocks, and the repository carries a PATHFINDING_PLAN.md file, which suggests that area is still being worked on rather than frozen.

Installing SoulFire and running a first bot session

The README does not inline installation steps. It says to follow the installation guide at soulfiremc.com/docs/installation, and the CLI has its own guide at soulfiremc.com/docs/guides/cli-mode. What the repository does give you is a Dockerfile and a source build path, so those are the two reproducible routes.

The Dockerfile builds from eclipse-temurin:25-jre, downloads the release jar as SoulFireDedicated-${VERSION}.jar from GitHub releases, exposes port 38765 and defines a healthcheck against http://localhost:38765/health. It takes a VERSION build argument:

ARG VERSION
ADD --chown=soulfire:soulfire https://github.com/soulfiremc-com/SoulFire/releases/download/${VERSION}/SoulFireDedicated-${VERSION}.jar /soulfire/soulfire.jar
EXPOSE 38765/tcp
HEALTHCHECK --interval=30s --timeout=10s --retries=5 \
  CMD curl -f http://localhost:38765/health || exit 1

That is the whole container contract: the jar is fetched at image build time, port 38765 is exposed, and the healthcheck polls /health on that port every 30 seconds with a 10 second timeout and 5 retries. Runtime data lives under /soulfire/data, which the Dockerfile creates and makes writable for the soulfire user.

Building from source follows four steps the README lists: install Java 25 or newer, download the source code from GitHub, run the Gradle build, then collect the jar. The README names the command and the output directories:

./gradlew build
# jar files are written to:
# client-launcher/build/libs
# dedicated-launcher/build/libs

Once a client or dedicated server is running, the README says to run help in the GUI or CLI for the command list, or read soulfiremc.com/docs/usage/commands. Account import and proxy import have their own documentation pages, which matters because a session is useless without at least one account and, on a rate-limited host, at least one proxy. Nightly builds are published through nightly.link for the main branch workflow, and the README notes the project is in active development.

Where SoulFire gets in your way

The plugin API is the sharpest edge. Mixin-based APIs reach into internal classes, and the README states outright that SoulFire can include breaking changes and that you should pin your plugin to a SoulFire version. If you want to write a plugin once and forget it, this project will not give you that. Budget for version bumps, and read the plugin example repository before committing to an interface.

The second constraint is the environment. A source build needs Java 25 or newer, which is ahead of what many CI images and developer machines carry by default. The container route avoids that, but it downloads the jar at image build time from a GitHub release URL, so an air-gapped or release-restricted environment cannot build the image as written.

The third is scope. This repository is the CLI and server only. If you want the GUI, you are installing the separate SoulFireClient project, and the README's demo page is a hosted preview rather than something you run locally. Version support is also delegated to the documentation rather than stated in the README, so confirming that your target Minecraft version is covered is a step you have to take yourself before planning a test run.

Finally, the legal and policy boundary is real. The README's warning puts responsibility for unauthorized use on you and notes that the developers are not responsible for your actions. Automated bot connections can look like abuse traffic to a hosting provider even when you own the server, so check that first.

SoulFire against headless Minecraft client libraries

The obvious alternative category is a headless Minecraft protocol library that you script yourself, such as a Java bot framework where you write the connection, movement and packet handling in your own code. The difference is where the work sits. With a library, you own the session lifecycle, the account handling, the proxy rotation and the concurrency model, and you get exactly the behaviour you wrote.

SoulFire inverts that. It ships the session machinery as a product: configurable bot counts and join delays, saved profiles, account and proxy import, built-in plugins, console commands and A* pathfinding, with a dedicated server and gRPC-Web SDKs on top. You trade control over internals for a working harness and an API surface you can drive from TypeScript or Python. If your goal is to test a server rather than to build a bot framework, the trade favours SoulFire. If your goal is a bot that does one unusual thing no plugin covers, a library plus your own code will be less friction than fighting a mixin API that changes between releases.

A second comparison point is the GUI client split. Projects that bundle everything into one artifact give you a single install and a single version to track. SoulFire's separate SoulFireClient repository means two things to keep in step, though it also means the dedicated server image stays small.

Licence and the cost of keeping SoulFire current

SoulFire is licensed AGPL-3.0, and the Docker image labels itself AGPL-3.0-only. That is a strong copyleft licence with a network clause: if you modify SoulFire and let users interact with it over a network, the AGPL's source-availability obligation is the part to read carefully. Running the unmodified dedicated server for your own testing is a different situation from shipping a modified SoulFire as part of a service. This is a description of the licence identifier, not legal advice; if you plan to redistribute or host a modified build, get your own reading of the AGPL.

The upgrade cost is mostly the plugin surface. The README's own instruction is to pin your plugin to a SoulFire version or update it when SoulFire changes, which is an admission that upgrades are not free. The release cadence shown in the repository is roughly monthly, with 2.9.0 in June, 2.9.1 in July and 2.10.0 in August, and the last push to the default branch was on 2026-08-27. Nightly builds exist for people who want to track main, but the README does not document a rollback path or a compatibility matrix between plugin versions and server versions, so pinning is the only mechanism the documentation offers.

Editorial conclusion

Adopt SoulFire if you own the Minecraft server you are testing and want scripted bots with a documented plugin API, a dedicated server image and gRPC-Web SDKs. Do not adopt it if you need a stable plugin ABI, because the README states SoulFire can include breaking changes and tells you to pin your plugin to a version. Verify first that your hosting provider permits automated bot testing, that Java 25 is available for a source build, and that the version you target appears in the supported versions list.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes