> ## 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.

# Serverhost

> The execution agent responsible for running Minecraft servers

## What is the Serverhost?

The Serverhost is a distributed execution agent that runs on each machine in your SimpleCloud infrastructure. It receives commands from the Controller and manages the actual lifecycle of Minecraft servers - from preparation to execution to cleanup.

## Key Responsibilities

### Server Lifecycle

The Serverhost manages the complete server lifecycle:

1. **Preparation** - Execute workflows, copy templates, install plugins
2. **Configuration** - Apply configurators to set ports, secrets, etc.
3. **Execution** - Launch the server process (Screen/Tmux or Docker)
4. **Monitoring** - Track server health and stream logs
5. **Cleanup** - Stop process and remove temporary files

### Workflow Execution

Workflows define the server preparation process:

* Copy template files to server directory
* Download and install plugins from registries
* Apply configuration based on server software
* Execute custom setup steps

### Plugin Management

Automatic plugin installation from multiple sources:

| Source   | Description                          |
| -------- | ------------------------------------ |
| Modrinth | Modern plugin/mod registry           |
| Hangar   | PaperMC's plugin repository          |
| Spigot   | SpigotMC resource pages              |
| URL      | Direct download from any HTTP(S) URL |

## Architecture

```mermaid theme={null}
flowchart TB
    subgraph Serverhost["Serverhost"]
        subgraph NATS["NATS Receiver"]
            Start["Start requests"]
            Status["Status reports"]
        end

        subgraph Workflow["Workflow Engine"]
            Copy["Copy"]
            Delete["Delete"]
            ForEach["ForEach"]
            Plugins["Plugin loading"]
            Config["Configurator actions"]
        end

        subgraph Deploy["Deployment Manager"]
            Screen["Screen/Tmux"]
            Docker["Docker"]
        end

        subgraph Configs["Configurators"]
            YAML["YAML"]
            JSON["JSON"]
            Props["Properties"]
            TOML["TOML"]
            Text["Text"]
        end
    end
```

## Execution Modes

### Screen/Tmux (Local)

The default execution mode using terminal multiplexers:

* **Screen** - Preferred, widely available on Linux
* **Tmux** - Alternative if Screen is unavailable

SimpleCloud components run as detached processes with component console access via:

```bash theme={null}
# Attach to the serverhost component console
sc attach serverhost
```

### Docker

Container-based execution for isolation:

* Each server runs in its own container
* Resource limits enforced by Docker
* Better isolation between servers
* Requires Docker to be installed

Configure the runner mode when starting:

```bash theme={null}
sc start --runner docker
sc start --runner screen
```

## Directory Structure

<Tree>
  <Tree.Folder name="secrets" defaultOpen>
    <Tree.File name="network-id.key" />

    <Tree.File name="network-secret.key" />

    <Tree.File name="serverhost-id.key" />
  </Tree.Folder>

  <Tree.Folder name="workflows" defaultOpen>
    <Tree.Folder name="internal" defaultOpen>
      <Tree.File name="setup.yml" />

      <Tree.File name="cleanup.yml" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.Folder name="options" defaultOpen>
    <Tree.Folder name="configurators">
      <Tree.File name="paper_velocity.yml" />

      <Tree.File name="velocity.yml" />
    </Tree.Folder>

    <Tree.File name="modrinth-platform-mappings.yml" />
  </Tree.Folder>

  <Tree.Folder name="templates" defaultOpen>
    <Tree.Folder name="every" />

    <Tree.Folder name="every_proxy" />

    <Tree.Folder name="every_server" />

    <Tree.Folder name="every_paper" />

    <Tree.Folder name="every_velocity" />

    <Tree.Folder name="_tagged">
      <Tree.Folder name="minigames" />
    </Tree.Folder>

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

  <Tree.Folder name="running" />

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

## Template Hierarchy

Templates are applied in a specific order, with later templates overwriting earlier ones. See [Templates](/en/manual/setup/templates) for full details and examples.

## Communication

### NATS Messaging

The Serverhost communicates with the Controller via NATS:

**Inbound (from Controller):**

* `{networkId}.serverhost.{id}.start` - Start server request

**Outbound (to Controller):**

* `{networkId}.server.{id}.status` - Server status updates
* `{networkId}.server.{id}.logs` - Log streaming
* `{networkId}.internal.serverhost.{id}.keep-alive` - Health checks

### State Synchronization

Every minute, the Serverhost:

1. Fetches active servers from Controller
2. Compares with locally running servers
3. Stops orphaned servers not in Controller's state

## Server Preparation Flow

When a start request arrives:

```mermaid theme={null}
flowchart TD
    A[Receive StartServerRequest] --> B[Validate server doesn't exist]
    B --> C[Find available port]
    C --> D[Execute setup workflow]

    subgraph Workflow["Setup Workflow"]
        D --> E[Copy from cache]
        E --> F[Copy 'every' templates]
        F --> G[Copy type-specific templates]
        G --> H[Copy software-specific templates]
        H --> I[Copy tagged templates]
        I --> J[Copy server-specific template]
        J --> K[Load plugins]
        K --> L[Apply configurator]
    end

    L --> M[Build JVM command]
    M --> N[Launch via Screen/Docker]
    N --> O[Report status to Controller]
```

## Configuration

Serverhost setup uses the current CLI setup options:

| Parameter                                        | Description                                                                 | Default                     |
| ------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------- |
| `--network`                                      | Network ID or slug                                                          | Interactive selection       |
| `--install-dir`                                  | Serverhost installation directory                                           | Interactive prompt          |
| `--host-name`                                    | Serverhost display name                                                     | Interactive prompt          |
| `--max-memory`                                   | Maximum serverhost memory, such as `80%` or `32gb`                          | Detected from system memory |
| `--start` / `--no-start`                         | Start SimpleCloud after setup or skip startup                               | Interactive prompt          |
| `--auto-install-deps` / `--no-auto-install-deps` | Install required dependencies automatically or skip dependency installation | Interactive prompt          |
| `--install`                                      | Install setup installables, such as `--install java:21`                     | None                        |
| `-y, --yes`                                      | Use non-interactive defaults where possible                                 | `false`                     |

## Monitoring

### Via CLI

```bash theme={null}
# Check serverhost status
sc status serverhost

# View serverhost logs
sc logs serverhost

# View specific server logs
sc server logs <group> <id>
```

### Keep-Alive

The Serverhost sends periodic keep-alive messages:

* Reports current version
* Reports installed Java runtime versions (exposed as `installed_java_versions` on serverhost API responses)
* Receives update notifications
* Maintains connection with Controller

<Note>
  Serverhosts automatically restart servers if the Serverhost itself restarts,
  based on synchronization with the Controller's state.
</Note>

## Related Topics

* [Configurators](/en/manual/configuration/configurators) - Server configuration system
* [Workflows](/en/manual/configuration/workflows) - Server preparation workflows