On this page

Quickstart

By the end of this page you will have a running Minecraft server with one plugin installed, and you will know which files Osmium wrote to make that happen.

This is the fast route. Your first server walks the same journey slowly, explaining each choice.

1. Check Osmium and Java#

bash
$ osmium --version
$ java -version

Java 21 is what the version used below needs. If java is missing, install a JRE before going on — see Installation.

2. Create the server#

Every question answered as a flag, so nothing is prompted:

bash
$ osmium create --name survival --engine Paper --version 1.21.1 --ram 4G --eula

--eula accepts Mojang's EULA on your behalf. Leave it off and Osmium asks.

You should see the engine download, then:

Created survival in /home/you/.config/osmium/servers/survival

3. See that it is registered#

bash
$ osmium list
NAME      ENGINE  VERSION  MEMORY  STATE    PATH
survival  PAPER   1.21.1   4G      stopped  /home/you/.config/osmium/servers/survival

The name in the first column is what --server takes.

4. Install a plugin#

Paper is a plugin server, so plugins are what it takes:

bash
$ osmium plugin add luckperms -s survival

Osmium resolves the whole change first — the plugin and anything it needs — prints the plan, and applies it only once every file has arrived and matched its published SHA-1.

5. Start it#

bash
$ osmium start -s survival
Started survival.
Follow its output with 'osmium logs -f'.

The server runs under a detached supervisor of its own. It keeps running after this command returns and after you close Osmium.

6. Watch it come up#

bash
$ osmium logs -s survival -f

Wait for the server to say Done. Press Ctrl+C to stop following — that stops the log, not the server.

7. Connect#

The server listens on port 25565 unless server.properties says otherwise. From the same machine, join localhost. To find the addresses that reach it from elsewhere:

bash
$ osmium expose -s survival --check

8. Stop it#

bash
$ osmium stop -s survival

This asks the server to shut down the way the console stop command does, so the world is saved on the way out. Osmium waits until it is really down before returning.

What just happened#

Inside the server folder Osmium wrote:

  • osmium.json — the manifest: category, loader, Minecraft version, memory, and the plugins you asked for. This is the file worth committing.
  • osmium.lock — what that resolved to: the exact build of every plugin, its file name, its SHA-1, and which plugin pulled in which.
  • the server jar and the run script, downloaded and generated for the engine and version you chose.
  • eula.txt, accepted because you passed --eula.
  • plugins/ with the jars the lock names, hard-linked out of the shared download cache where the filesystem allows it.
  • .osmium/ — the supervisor's private state: the process id, the control socket and server.log. Backups go in .osmium/backups.

Outside the server folder, Osmium touched only its own registry and settings in your user config directory, and the download cache in your user cache directory. See Configuration for the exact paths.

Next#

Your first server — the same journey deliberately, one decision at a time.