PhantomBot: a Java Twitch chat bot with a web panel on port 25000

A channel bot with a panel, not a script collection

PhantomBot is described as an actively developed open source interactive Twitch bot with a vibrant community, and the README calls it a Twitch chat bot powered by Java. The project description adds that it provides entertainment and moderation for a channel so the streamer can focus on the game and the viewers.

The feature list is what distinguishes it from a pile of chat scripts. Out of the box it has a built-in web panel, enhanced moderation, games, a point system, raffles, custom commands and a music player. It can also be integrated with services including Discord, TipeeeStream, StreamLabs and StreamElements, and further functionality comes from third-party modules.

The integration surface is the part that makes it a platform rather than a program. A music player in a chat window is a feature, and a music player that plays a request bought on a donation platform is an integration with a business model behind it, and the difference between a bot that can be pointed at a platform and one that cannot is the difference between a tool and a project.

Underneath, the repository is a Java project with a separate directory for JavaScript sources, and the topics list mentions a JavaScript engine for the JVM, which is how chat commands and modules are written on top of a Java core. The build is Ant with Ivy for dependency resolution, which is an older stack but one that has the advantage of not requiring a build tool the operator has to learn.

The licence is GPL-3.0, the site is phantombot.dev, the last push was on 2026-10-19, and the release history shows three patch releases of the same line in the three days before that, which is a project shipping continuously rather than occasionally.

The install ends in a browser panel with a self-signed certificate

The quick start is a download and a launcher, and the steps are worth following in order because two of them are easy to get wrong.

You download the latest release for your platform, and the README notes that macOS on Apple Silicon needs the arm64 package rather than the Intel one. You extract it wherever you want it to live, and on Linux and macOS you apply execute permissions to the launchers:

chmod +x launch.sh

If you plan to run the bot as a background service later, the same applies to the service launcher. Then you start it, with a batch file or a PowerShell script on Windows and the shell script elsewhere:

./launch.sh

The web panel comes up on port 25000, and the README is upfront that a browser security warning is normal, because the panel uses self-signed certificates by default. If you reach it from another machine, you need the firewall and port forwarding set up to allow that port.

Then there is the setup, which is where the two-part OAuth arrangement becomes clear. You open the bot setup and OAuth page, and the login screen shows a username and password that were auto-generated and printed in your terminal window, so you can read them from the console where the bot is running. You fill in the name of the Twitch channel to join, and optionally set your own admin credentials for the panel. You save the configuration with the floating button, and then follow the OAuth instructions, where the README insists on doing both flows: the bot OAuth, which sets the user the bot posts as, and the broadcaster OAuth, which authorises use of the Twitch API on your behalf.

Skipping the second one is the classic mistake, and the README has thought about it, which is why it spells out which is which.

Shutdown has a procedure, because the database is not forgiving

The closing and shutting down section is short, and it is the clearest sign of how the project treats its own state.

The README says that to reduce the risk of database corruption you should only close the bot in one of two ways. If you started it from a terminal, you type exit and press enter, or you press control C. If you started it as a background service with the service launcher, you send the termination signal with the process id. Either way, you then wait for the message that the bot is exiting to appear.

That last instruction is the one people skip. A process that is killed rather than asked to stop can leave a database in a state that needs repair, and a bot that is run in a container that gets recreated will be killed rather than asked to stop, so anyone deploying the Docker image needs to think about how the container is stopped.

The build tooling offers a small parallel. The Makefile has a target that finds the running process and sends it the signal, using the process list and a search for the jar file, and a separate target that stops the process and one that rebuilds and runs. So the project itself treats a clean stop as an operation with a tool behind it, not as an afterthought.

The wider point is about the architecture. The bot is a stateful service with a web panel, a database and OAuth credentials, not a stateless script, and the documentation reflects that. It also means that running it somewhere with a supervisor that kills processes aggressively, which is a common container default, is the scenario most likely to produce the corruption the README warns about.

Platform support is specified down to the glibc version

The system requirements section is unusually precise, and it reads like a support matrix rather than a marketing claim.

On Windows, version 10 or 11 and Windows Server 2019, 2022 or 2025 are supported on 64-bit machines with no additional requirements, while the 32-bit builds need the Eclipse Temurin 17 runtime installed separately. On macOS, version 12 or later works on both Intel and Apple silicon in 64-bit mode with no extra requirements.

On Linux the list separates the library version from the architecture. A glibc-based system on Intel or AMD needs glibc 2.12 or later, on 64-bit ARM it needs 2.17 or later, and on 32-bit ARM with hardware floating point it needs 2.23 or later. The Raspberry Pi 4 and 5 with 64-bit enabled are given as the example for that tier, and the Pi 3 for the 32-bit one. A musl-based system such as Alpine needs the Temurin 17 runtime, and the requirement is written as equivalent to Alpine 3.5 or later on 64-bit.

Anything else is deferred to the support list for JDK 17 at the Adoptium project.

Two things are worth drawing out. First, the 32-bit tiers are still supported, which is unusual for a Java application today and tells you something about the audience, which includes people running the bot on a small single board computer beside their streaming setup. Second, the glibc floor of 2.12 is old, which means the bot runs on a lot of older distributions.

So the practical answer to whether it will run on your machine is usually yes, and the requirements table exists to tell you which runtime package to add in the two cases where the answer is not quite.

Docker images, a compose file, and a build that fetches its own tools

PhantomBot publishes official builds to Docker Hub and to the GitHub container registry, and the repository carries a compose file, so a container deployment is a supported path rather than a community workaround.

The compose file is commented in a way that explains the choices, which is unusual and useful. The service pulls the image from the GitHub container registry, the panel port is mapped so it is reachable from the host, and the comments warn that the port should not be changed because the base port setting in the bot login file is tied to it, and that it is not necessary in Docker since the mapping is internal to each container. There is a second service, brought up with a profile, that handles automatic updates, and the two commands are:

docker compose up --pull always -d

docker compose --profile ouroboros up --pull always -d

The image itself is built in stages. The builder stage is the Temurin 17 JDK, and the interesting part is that Ant is not assumed to be present, so the build downloads the Ant package from the distribution, installs it while ignoring the dependencies it does not need, and then removes both the package and the apt lists so the layer stays small. The Ant build then retrieves the dependencies with Ivy and produces a jar, and the project name and version become build arguments.

The result is a runtime image that carries a built jar and a small dependency directory. For a team that already runs containers, that is a clean answer, and the profile-based auto-update service is a sensible touch for a bot that is expected to keep running.

The repository also carries a dev container configuration, a separate development resources directory with a setup guide, and an Unraid template, which tells you the deployment shapes the project supports.

Exception reporting is the section to read before you deploy

The last part of the README is about error reporting, and it is unusually detailed for a project README, which usually means it has caused confusion.

The project uses Rollbar to report exceptions to the development team automatically. The notice then spells out the boundaries. OAuth tokens, client identifiers and API secrets are not sent. All information is kept private. Data is only sent when an exception occurs, and very common exceptions are excluded, with connection timeouts given as the example.

The path is also described. Exceptions are sent through a server owned by the main maintainer for additional filtering before continuing on to Rollbar. No data is saved on that server beyond the normal logs used for denial of service mitigation, those logs may include IP addresses and are deleted after five weeks, and IP addresses are not sent onward.

For a bot that holds a broadcaster's OAuth token and a channel's identity, this is the part of the documentation that matters most, because an exception in a long-running Java process can carry a request object with it. The README's claim is that the credentials are excluded, and the filtering server and the five week log retention are described as the mechanism. A reader with a compliance obligation should verify that against the code, because the claim is only as good as the filter.

Everything else in the project is straightforward, and it is worth saying that plainly. The licence is GPL-3.0, the security policy is in the repository, the upgrade instructions are on the documentation site, and the support channel is a Discord server where the README asks people not to use direct messages or mentions.

Editorial conclusion

Adopt PhantomBot if you run a Twitch channel and want a self-hosted bot with moderation, points, raffles and a web panel without writing any of it, and you are prepared to run a Java service that holds OAuth tokens for your channel. Do not adopt it if you cannot keep the process shut down cleanly, because the README is explicit that the shutdown procedure exists to reduce the risk of database corruption, and a container that gets killed is a database that is not closed properly. Before you deploy, read the exception reporting section, because exceptions from your instance are sent to the maintainers, and decide whether the package and Docker images, which pull a JDK and a build toolchain at image build time, are acceptable in your environment.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. PhantomBot/PhantomBot on GitHub
3. Project website
4. README
5. Releases