Instance Layout

An instance is a directory with mc.kdl at its root. All mc commands run from that directory, and everything the instance needs lives under it:

myserver/
├── mc.kdl
├── mc.lock
├── .java/
├── .minecraft/
├── .tunnel/
│   ├── playit.toml
│   └── playitd.log
├── backups/
├── instance/
│   ├── eula.txt
│   ├── server.properties
│   ├── mods/
│   └── myserver/
└── temp/

Only one running server is allowed per instance directory; a second mc run in the same directory refuses to start.

mc.kdl

The manifest describing the instance — the only file you author. See The Manifest Format.

mc.lock

The lockfile, written in KDL. It holds the mods resolved from the manifest, including their required dependencies, and the identity resolved for every player named in the manifest. The mod entries are rewritten from the manifest’s pinned versions on every start; the player entries are added by the player commands and by a start that meets a name not yet recorded.

.java/ and .minecraft/

Installed Java runtimes and Minecraft binaries, keyed by version, shared by every start of this instance. Safe to delete while the instance is stopped; whatever is missing is downloaded again on the next start.

.tunnel/

Present when the manifest has a tunnel section. Holds the installed tunnel agents, keyed by version like .java/, the agent’s log in playitd.log when its output is not shown in the terminal, and playit.toml, the secret that links the agent to a tunnel provider account. The secret file is created readable only by the owning user when the agent is first claimed, and mc refuses to start if its permissions have been loosened. Deleting it makes the next start claim a new agent; mc tunnel claim --force does the same on demand. See Tunnels.

Instances created before tunnels existed have no /.tunnel entry in their .gitignore; add one before committing.

backups/

The default destination for backup archives when local storage is used. The directory is dedicated to this instance’s backups; see Backups.

instance/

The live working directory of the Minecraft process. Notable contents:

• eula.txt — generated from the eula key in the manifest.
• server.properties — generated from the manifest on every start; manual edits are overwritten. Use the properties block of the server section in mc.kdl instead. When the file holds secrets, such as an RCON password, mc creates it readable only by the owning user and refuses to start if its permissions have been loosened.
• mods/ — the installed mods. This directory is fully managed: mc adds and removes jars to match the lockfile, so a jar placed here by hand is deleted on the next start. Declare URL mods in the manifest instead.
• whitelist.json, banned-players.json, banned-ips.json, ops.json — the player lists, generated from the players section of the manifest on every start. Changes the server writes to them on its own are replaced at the next start; use mc allow, mc ban, and mc op instead.
• myserver/ — the world, named after the instance’s name. Everything else Minecraft writes at runtime (logs, player data, and so on) also lives here and is left untouched by mc.

temp/

Scratch space for in-flight downloads and archives. Cleared when the instance starts; safe to delete while nothing is running.