Quick-Start Guide

This is a brief guide to getting an EnderChest set up and linking. It covers the most important command-line operations and how to make best use of shulker boxes.

Locating Your Minecraft Instances

Before setting up an EnderChest, it's a good idea to take a minute and figure out where all of your Minecraft data is actually stored. This will vary based on your operating system and the launchers you use. This document, for example, tells you how to find the official launcher data. MultiMC-derived programs like PrismLauncher will often have a "Folder" button that will take you to the location of each instance, which is especially helpful for the Flatpak distribution.

Selecting a "Minecraft Root"

Once you have the lay of the land, the next thing you'll want to do is decide where you want your EnderChest folder to live. This could be your home folder (~ or C:\Users\yourusername\, in the folder containing your MultiMC instances directory, or anywhere that's convenient for you. Go to that directory in your terminal.

Tip

You can run any EnderChest command from any location by explicitly specifying the Minecraft root, e.g.

enderchest craft --root /path/to/my_minecraft_stuff

Tip

You can also specify your Minecraft root by using an enviroment variable.

export MINECRAFT_ROOT=/path/to/my_minecraft_stuff

Creating an EnderChest

When ready, run the command:

enderchest craft

to begin the guided setup process. This process will ask you about directories to look for Minecraft installations inside. Note that these will be the folders containing .minecraft, not the .minecraft folders themselves.

You'll also be prompted for the address of another EnderChest installation you want to sync with. For now, I'll assume that this is your first EnderChest, so leave that answer blank. When you're ready to create another EnderChest on another machine, the Managing Remotes section will have you covered.

Once the installer finishes, you'll end up with a new folder inside your current directory (or Minecraft root) named EnderChest along with a file inside that folder named enderchest.cfg. Feel free to open up that file in your favorite text editor and take a look. It's designed to be easily edited to make it easy to, for example, manually add a tag to an instance.

Info

When a given entry can have multiple values, you can separate those values by commas, e.g.

tags = vanilla_plus, modded, sodium

or by putting each entry on its own (indented) line, e.g.

tags =
    aether
    modded
    optifine

PSA for Flatpak users

If you're using a launcher installed via Flatpak, make sure to give it permission to read from and write to your EnderChest folder, if not your entire Minecraft root. Use of Flatseal is highly recommended.

Registering Additional Instances

Once you have an EnderChest installed, you can register additional instances at any time by using the gather action. Running:

enderchest gather instance <path>

will recursively search the provided directory for folders named .minecraft and attempt to register them.

Tip

You can control how much information gets displayed when running EnderChest commands by using the --verbose (-v) and --quiet (-q) flags.

Creating Shulker Boxes

Once you've populated your EnderChest configuration with all the Minecraft instances you want to manage, it's time to start crafting shulker boxes.

Running:

enderchest craft shulker_box <name>

will take you through a guided setup that will let to control how your shulker box will know which instances will link to it along with what other remote EnderChest installations will use it. At the conclusion of the process you'll end up with a folder within your EnderChest that's pre-populated so as to mirror what you'd see in a .minecraft folder.

Moving Files into Your Shulker Box

If you have existing Minecraft installations, now is the time to start moving the assets from those instances into your shulker box. Just put them in the exact same place inside the shulker box that they'd be inside of .minecraft (so resource packs go in resourcepacks, worlds go in saves, etc.)

Linking Entire Folders

During the shulker box creation process, you were prompted to select any folders that you wanted to symlink whole-hog. This is useful for things like screenshots or logs where files will be generated by the instance and not just accessed or updated.

Important!

By default, for the purposes of linking EnderChest treats any folder that's not at the top level (e.g. saves/my world) as a file that's symlinked in its entirety. You can change this behavior by setting the max-link-depth parameter in the shulker box config, but doing so should be considered highly experimental.

Linking Your Instances

Once everything is set up, to actually link up all of your instances, you just need to run:

enderchest place

Important!!

Starting with Minecraft 1.20, Mojang by default no longer allows worlds to load if they are or if they contain symbolic links. Obviously this will be a problem if you're using EnderChest to centralize and organize your world saves.

By default, EnderChest will offer to create an allowed_symlinks.txt folder inside any 1.20+ instance that doesn't have one already and update the file to blanket-allow symbolic links into your EnderChest.

If you would prefer to do this by hand or not at all, you can edit your enderchest.cfg and change the value for offer-to-update-symlink-allowlist to False. EnderChest will never create any file or symlink without your consent and will never place a symlink pointing directly to a place outside of your EnderChest.

If you would like to get a full report of all symlinks EnderChest places, you can run:

enderchest place --verbose

to get a full audit.

As EnderChest places all your links, it will stop if at any point there's already a file or a non-empty folder at that location. Sometimes that happens because you forgot to clean out an existing instance. Other times, your shulker box configurations might be conflicting with each other. Regardless, rather than just overwriting your data, EnderChest will ask you how you want to proceed. And once you've fixed the issue, you can just run

enderchest place

again--running place multiple times is completely safe (and is something you should do regularly! and particularly after any shulker box modification or file sync!).

Managing Remotes

Once you've finished setting up an EnderChest on a given computer, the next thing to consider is setting it up on another one. To do that, you'll need to set up some form of file transfer. EnderChest's preferred transfer protocol is rsync, an extremely efficient open source tool for performing backups and generally moving files between two locations. Most Linux distributions (including SteamOS) come with a sufficiently recent version of rsync preinstalled (EnderChest requires rsync 3.2 or newer), and Mac users can upgrade their rsync easily via homebrew, MacPorts or conda.

Windows users may be able to get EnderChest working with rsync via Cygwin or WSL, but this is not currently supported, and Windows users may be better off using a different protocol.

To register a remote with your EnderChest, you just need to run the following command:

enderchest gather enderchests <remote>

where <remote> is the URI to the remote chest.

Understanding URIs

A Uniform Resource Identifier, or URI, is a way of referencing files or folders--oftentimes on other computers-- in a standard way. URLs, like you're familiar with from web browsers, are a type of URI. The format of a URI typically follows the following schema:

<protocol>://[[<username>@]<host>[:port]<path>[?<query>]

The important bits right now are: - the protocol must be one that's supported by both EnderChest and by your machine - the host can be the local IP of your remote machine, but most home routers support connecting to machines via their hostname. This is much better for users whose routers don't assign machines statis IP addresses. - the path must be URL encoded to transform special characters (especially spaces) into a single unambiguous string - the path must be absolute, (and in the URI syntax must start with a /), starting from the computer or service's root directory (hence the / for macOS and Linux users) - the path does not point to an EnderChest, but to the folder containing the EnderChest.

As an example, let's say I have an EnderChest installed on my Steam Deck (hostname: "steamdeck") directly inside my home directory (so ~/EnderChest). If I'm setting up an EnderChest on my couch gaming laptop and want to sync with my Deck, the URI for it will be: rsync://deck@steamdeck/home/deck

Tip

You can use this website to encode any file name or POSIX path as a URI. You can also get the URI to your current directory in Python by running the following code:

>>> from pathlib import Path
>>> print(Path().absolute().as_uri())

While that will give you the file:// protocol, URI you can then just replace the file:// part (make sure not to grab the third slash!) and replace it with the protocol://[user@]hostname[:port] of your choice.

Syncing

Once you have some remote EnderChests set up, the way you sync with them is via the close and open actions:

enderchest close

will push your local changes to all registered remote chests

enderchest open

will pull changes from your other EnderChests while

Info

Where you have multiple remotes specified, enderchest open will only pull changes from one, prioritizing them in the order that they're listed, and stopping once it manages to sync successfully.

In contrast, enderchest close will push changes to all registered remotes.

This is useful for when you have EnderChests running on laptops or handhelds that are not always on, or not always on the same network as the other devices, but it means you need to be careful that the first remote listed in your config is the one most likely to be up-to-date.

Sync operations are destructive and won't hesitate to wipe out all the files in an EnderChest if you have your remote mis-configured. That's why all sync operations support the --dry-run flag, which lets you preview the operations that will be performed before they're actually run.

In fact, by default, all sync operations will perform a dry run first and give you five seconds to review the dry run log and interrupt the sync if things are about to go sideways (documentation for overriding this behavior is available in the CLI docs).

Bonus

Starting with v0.1.3, after a successful enderchest open, EnderChest will automatically update all of your instances' symlinks, saving you from needing to remember to run:

enderchest place

(this behavior can be disabled by editing the place-after-open setting in your enderchest.cfg file).

Uninstalling

Info

Even if you uninstall the EnderChest package, the symbolic links it created will continue working until you replace them or move your EnderChest / Minecraft folders.

If you ever decide that the symlink life isn't for you, run the command:

enderchest break

This will go through all of your instance folders, replacing any symlinks that point into the EnderChest folder with hard copies of those resources.

Note

If your EnderChest itself contained links pointing to outside the EnderChest (say, EnderChest/global/screenshots → ~/Pictures/Screenshots), then after breaking, your instances will simply contain direct links to those files and folders.

After that completes, you can remove the package via your Python package manager, e.g.

pipx uninstall enderchest

and safely delete your EnderChest folder

Danger

Make sure before you delete your EnderChest folder to move or preserve any files or folders you've been manually synchronizing for non-Minecraft games or applications, as those links are not automatically replaced by the break command.