> ## Documentation Index
> Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Root Setup

> Run SimpleCloud across multiple machines with distributed serverhosts

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:

```bash theme={null}
/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:

```bash theme={null}
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

<Tip>
  Each serverhost needs a unique identity. The CLI generates credentials
  automatically and stores them in the `secrets/` directory.
</Tip>

### Verify Connection

After adding, verify the local serverhost component is running:

```bash theme={null}
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

| Directory    | Purpose                            | Sync?                |
| ------------ | ---------------------------------- | -------------------- |
| `templates/` | Server templates, plugins, configs | Yes                  |
| `workflows/` | Workflow definitions               | Yes                  |
| `options/`   | Configurator settings              | Yes                  |
| `secrets/`   | Network credentials                | No - unique per host |
| `running/`   | Active server instances            | No - local only      |
| `logs/`      | Serverhost logs                    | No - local only      |

<Warning>
  Never synchronize the `secrets/` directory. Each serverhost needs its own
  unique identity credentials.
</Warning>

### Finding Your SimpleCloud Directory

The installation path is user-configurable. Your serverhost directory contains:

<Tree>
  <Tree.Folder name="simplecloud" defaultOpen>
    <Tree.Folder name="templates" defaultOpen>
      <Tree.File name="Sync this" />
    </Tree.Folder>

    <Tree.Folder name="workflows" defaultOpen>
      <Tree.File name="Sync this" />
    </Tree.Folder>

    <Tree.Folder name="options">
      <Tree.File name="Sync this" />
    </Tree.Folder>

    <Tree.Folder name="secrets">
      <Tree.File name="DO NOT sync" />
    </Tree.Folder>

    <Tree.Folder name="running" />
  </Tree.Folder>
</Tree>

### Initialize Sync on the Primary Serverhost

Run this on the serverhost that should act as your primary sync host:

```bash theme={null}
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.

<Note>
  If you run SimpleCloud as root, add `--as-root` so the CLI uses
  `syncthing@root.service`.
</Note>

### Join from Another Serverhost

On the new serverhost, run the `sc sync join ...` command printed by `sc sync init` or `sc sync add`.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
sc sync add --join-name serverhost-3
```

Check synchronization status on any host:

```bash theme={null}
sc sync status
```

### Verify Synchronization

Test that synchronization works:

```bash theme={null}
# 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:

| Strategy       | Use Case                                          |
| -------------- | ------------------------------------------------- |
| Any host       | Load balancing across all machines                |
| Specific hosts | Dedicated hardware for resource-intensive servers |
| Geographic     | Players connect to nearest serverhost             |

### File Sync Settings

| Setting            | Recommended    | Reason                             |
| ------------------ | -------------- | ---------------------------------- |
| Folder Type        | Send & Receive | Allows changes from any serverhost |
| File Versioning    | Simple         | Keeps backup copies                |
| Ignore Permissions | Enabled        | Avoids permission conflicts        |

### Exclude Cache from Sync

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="Serverhost not appearing in list">
    **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`
  </Accordion>

  <Accordion title="Syncthing devices not connecting">
    **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
  </Accordion>

  <Accordion title="Files not syncing between hosts">
    **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`
  </Accordion>

  <Accordion title="Servers starting on wrong host">
    **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
  </Accordion>

  <Accordion title="Conflict files appearing">
    **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
  </Accordion>
</AccordionGroup>

## Related Topics

* [Templates](/en/manual/setup/templates) - Template hierarchy and management
* [Workflows](/en/manual/configuration/workflows) - Workflow configuration
* [Serverhost](/en/manual/introduction/architecture/serverhost) - Serverhost architecture