Dedicated Mode

When to use a dedicated server

SoulFire has a client and a server. The client provides the user interface. The server manages bot connections, data, permissions, and commands.

Why use dedicated mode?

A dedicated server keeps running after you close the GUI or CLI. You can run it on a remote machine or as a background process on your computer.

The GUI and CLI use an integrated server by default. The integrated server stops when its client stops.

Several GUI and CLI clients can connect to one dedicated server. You can also run several dedicated servers on different ports.

CLI mode is different from dedicated mode. Its integrated server does not accept connections from other clients.

How to start the server in dedicated mode

Install Java 25. Then download the latest dedicated server .jar from the download page. Run this command:

java -Xmx$RAM -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true -jar SoulFireDedicated.jar

Replace $RAM with the memory limit for the server. If you omit -Xmx$RAM, Java uses up to 25% of the total system memory. For example, use -Xmx120G to set a 120 GB limit.

Server options

A dedicated server listens on a configured IP address and port. Use these options:

Pass these options to Java as system properties. This example changes the port:

java -Dsf.grpc.port=12345 -Xmx$RAM -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true -jar SoulFireDedicated.jar

Terminal flags

Set -Dterminal.jline=true or -Dterminal.jline=false to enable or disable the interactive terminal. The terminal uses JLine, the same library used by Minecraft and Velocity. Set -Dterminal.ansi=true or -Dterminal.ansi=false to enable or disable terminal colors.

Firewall

Open the SoulFire port in the server firewall. If the server is behind a router, forward the port with the same process as a Minecraft server.

Generate an access token

Clients need an access token to connect. Run this command in the interactive server terminal:

generate-token api

Keep the token secret. Anyone with the token can connect through the GUI or CLI and use your permissions.

Docker images

The dedicated server image is available on Docker Hub. See the Docker guide for examples.

Next steps

Connect to the server from the GUI, CLI, or SDK. The server runs bot connections, checks proxies, and authenticates accounts.