Configuration

By the end of this page you will be able to read and hand-edit every file Osmium writes, and know exactly where each one lives.

There are three files. Two describe a server and sit inside it; one holds Osmium's own settings and sits in your config directory.

---

osmium.json — the manifest#

Where it lives: in the server's own folder, beside the jar. It is written when the server is created, and rewritten whenever what you asked for changes.

The manifest is a statement of intent: what this server runs, how much memory it gets, and which mods and plugins were asked for. It is small, readable, and the file worth committing.

{
 "category": "Mod Loader",
 "loader": "Fabric",
 "version": "1.21.1",
 "ram": "6G",
 "mods": {
  "sodium": "0.5.8",
  "spectrum": "*"
 },
 "plugins": {}
}

Field reference#

mods and plugins are separate because they are installed into different folders and are never interchangeable: a Fabric mod in plugins/ is ignored, and a Paper plugin in mods/ is ignored just as quietly. Which one a server uses follows from loader.

What a mod entry can say#

Each value is one of exactly two things, never a third:

There is no range syntax, because there is nothing here to compare or order. Minecraft mods do not carry version numbers a range could be written against: an author may call a build 1.10.5-fabric, 0.102.0+1.21.1 or mc1.21.1-0.5.8.

---

osmium.lock — the resolution#

Where it lives: beside osmium.json, in the server's folder.

The lock is the record of what the manifest resolved to: exact builds, file names, hashes, and which mod pulled in which. It is what makes an install reproducible. Hand someone the manifest and the lock and osmium install gives them the same server, file for file. Hand them just the manifest and it resolves afresh.

{
 "lock_version": 1,
 "loader": "Fabric",
 "game_version": "1.21.1",
 "packages": [
  {
   "slug": "fabric-api",
   "kind": "mods",
   "project": "P7dR8mSH",
   "version": "wKMkAxrp",
   "version_number": "0.102.0+1.21.1",
   "channel": "release",
   "filename": "fabric-api-0.102.0+1.21.1.jar",
   "url": "https://cdn.modrinth.com/data/P7dR8mSH/versions/wKMkAxrp/fabric-api-0.102.0%2B1.21.1.jar",
   "sha1": "0a1b2c3d4e5f60718293a4b5c6d7e8f901234567",
   "size": 2216448,
   "explicit": false,
   "required_by": ["spectrum"]
  }
 ]
}

Top-level fields#

Fields of one package#

packages is kept sorted by kind and slug, so two resolutions of the same manifest produce byte-identical files and a diff shows only what actually changed.

---

Editing by hand#

Safe to edit in osmium.json: ram, and the entries in mods and plugins. Adding a slug with "*" and running osmium mod install is exactly what osmium mod add does. Changing a value to a build number pins it.

Not safe to edit by hand: loader and version. They say what the server runs, and changing them in the file changes nothing about the jar on disk — the manifest would then describe a server that does not exist. Use osmium migrate instead.

Osmium rewrites osmium.json whenever what you asked for changes, and osmium.lock on every operation that changes what is installed. Both are written whole; formatting and key order are not preserved, and packages is re-sorted.

On invalid JSON, the command that read the file fails and says which file it could not read. Nothing is written, and the server is not touched.

Jars Osmium did not install are never touched. Every plan names them, and osmium mod track adopts them when you want them managed.

---

Version control#

Commit:

• osmium.json — the manifest.
• osmium.lock — the lock, which is what makes the rebuild exact.
• server.properties, if the server's settings are worth sharing.

Ignore:

• mods/ and plugins/ — jars, all recoverable from the lock.
• the server jar and the run script — downloaded at install time.
• the world folders — large, and rarely what a repository is for. Use osmium backup.
• .osmium/ — the supervisor's private state: the process id, the control socket, server.log, and .osmium/backups.
• eula.txt — an agreement between you and Mojang, not a project file.

A .gitignore that covers it:

mods/
plugins/
.osmium/
*.jar
world*/
eula.txt
logs/

---

config.json — Osmium's own settings#

Where it lives:

It is created on first run, and most of it is edited from the Settings screen rather than by hand.

{
  "theme": "Teal",
  "default_server_dir": "/home/you/minecraft",
  "default_ram": "4G",
  "manage_layout": "servers-left",
  "hidden_panes": []
}

---

Every path Osmium touches#

Servers you created anywhere else live wherever you put them, and Osmium only keeps a path to them.