Skip to main content
A multi-root setup allows you to run Minecraft servers across multiple physical or virtual machines, all managed by a single SimpleCloud controller. This guide covers adding serverhosts and synchronizing files between them.

​
Prerequisites

  • An existing SimpleCloud network with at least one serverhost
  • Additional machines to run serverhosts on
  • Root or sudo access on each machine

​
Part 1: Adding Serverhosts

​
Install SimpleCloud on Each Machine

On each machine that will run a serverhost, install the SimpleCloud CLI: 
/bin/bash -c "$(curl -fsSL https://get.simplecloud.app)"

​
Add Serverhost to Network

Use the CLI to add a new serverhost to your existing network: 
sc serverhost add
The CLI will prompt you to:
  1. Select your network - Choose the network your controller manages
  2. Authenticate - Log in with your SimpleCloud account
  3. Configure the serverhost - Set port ranges and other options
Each serverhost needs a unique identity. The CLI generates credentials automatically and stores them in the secrets/ directory.

​
Verify Connection

After adding, verify the local serverhost component is running: 
sc status serverhost
You should also see the new serverhost in the dashboard after it connects to the Controller.

​
Part 2: Synchronizing Files

With multiple serverhosts, you need to keep templates and workflows synchronized. We recommend using Syncthing for automatic file synchronization.

​
What to Synchronize

DirectoryPurposeSync?
templates/Server templates, plugins, configsYes
workflows/Workflow definitionsYes
options/Configurator settingsYes
secrets/Network credentialsNo - unique per host
running/Active server instancesNo - local only
logs/Serverhost logsNo - local only
Never synchronize the secrets/ directory. Each serverhost needs its own unique identity credentials.

​
Finding Your SimpleCloud Directory

The installation path is user-configurable. Your serverhost directory contains:
simplecloud
templates
Sync this
workflows
Sync this
running

​
Initialize Sync on the Primary Serverhost

Run this on the serverhost that should act as your primary sync host: 
sc sync init --name serverhost-1
The CLI prepares the managed directories, ignores templates/cache/, configures Syncthing for templates/, workflows/, and options/, stores the folder IDs in .simplecloud-sync.json, and prints a sc sync join ... command for the next serverhost.
If you run SimpleCloud as root, add --as-root so the CLI uses syncthing@root.service.

​
Join from Another Serverhost

On the new serverhost, run the sc sync join ... command printed by sc sync init or sc sync add. 
sc sync join \
  --primary-device-id PRIMARY_DEVICE_ID \
  --primary-name serverhost-1 \
  --templates-id TEMPLATES_FOLDER_ID \
  --workflows-id WORKFLOWS_FOLDER_ID \
  --options-id OPTIONS_FOLDER_ID \
  --name serverhost-2
After the join command finishes, it prints a sc sync approve ... command.

​
Approve the Joining Serverhost

Run the printed approve command on the primary serverhost: 
sc sync approve --device-id JOINING_DEVICE_ID --name serverhost-2
For additional serverhosts later, run this on the primary serverhost to generate a fresh join command: 
sc sync add --join-name serverhost-3
Check synchronization status on any host: 
sc sync status

​
Verify Synchronization

Test that synchronization works: 
# On Serverhost 1
echo "sync test" > $CLOUD_DIR/templates/sync-test.txt

# Wait a few seconds, then check on Serverhost 2
cat $CLOUD_DIR/templates/sync-test.txt

# Clean up
rm $CLOUD_DIR/templates/sync-test.txt

​
Best Practices

​
Server Distribution

Configure groups to specify which serverhosts can run them:
StrategyUse Case
Any hostLoad balancing across all machines
Specific hostsDedicated hardware for resource-intensive servers
GeographicPlayers connect to nearest serverhost

​
File Sync Settings

SettingRecommendedReason
Folder TypeSend & ReceiveAllows changes from any serverhost
File VersioningSimpleKeeps backup copies
Ignore PermissionsEnabledAvoids permission conflicts

​
Exclude Cache from Sync

The templates/cache/ folder contains locally generated files. Consider excluding it from synchronization to avoid unnecessary transfers.

​
Troubleshooting

Symptom: After sc serverhost add, the host doesn’t show up.Solutions:
  1. Check the serverhost is running: sc status serverhost
  2. Verify network connectivity to the controller
  3. Check credentials in secrets/ directory exist
  4. Review serverhost logs: sc logs serverhost
Symptom: Devices show as “Disconnected”.Solutions:
  1. Ensure firewall allows port 22000 TCP and UDP
  2. Run sc sync status on each host
  3. Verify the sc sync approve ... command was run on the primary host
  4. If running as root, include --as-root with each sc sync command
Symptom: Template changes don’t appear on other serverhosts.Solutions:
  1. Run sc sync status and check that templates, workflows, and options are configured
  2. Verify the folder IDs in .simplecloud-sync.json match across hosts
  3. Confirm the joining host was approved with sc sync approve
  4. Review Syncthing connection errors reported by sc sync status
Symptom: Servers start on unexpected serverhosts.Solutions:
  1. Check group configuration for host restrictions
  2. Verify all serverhosts have required templates synced
  3. Review serverhost availability in the dashboard
Symptom: Files with .sync-conflict in the name appear.Cause: Same file modified on multiple hosts simultaneously.Solutions:
  1. Review conflict files and choose correct version
  2. Avoid editing same file on multiple hosts at once
  3. Designate one host as “primary” for template editing