Skip to main content

​
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:
SourceDescription
ModrinthModern plugin/mod registry
HangarPaperMC’s plugin repository
SpigotSpigotMC resource pages
URLDirect download from any HTTP(S) URL

​
Architecture

​
Execution Modes

​
Screen/Tmux (Local)

The default execution mode using terminal multiplexers:
  • Screen - Preferred, widely available on Linux
  • Tmux - Alternative if Screen is unavailable
Servers run as detached processes with console access via: 
# Attach to a server console
sc attach <server-name>

​
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: 
sc start --runner docker
sc start --runner screen

​
Directory Structure

secrets
network-id.key
network-secret.key
serverhost-id.key
workflows
internal
setup.yml
cleanup.yml
options
modrinth-platform-mappings.yml
templates
every
every_proxy
every_server
every_paper
every_velocity
cache
running
logs

​
Template Hierarchy

Templates are applied in order, with later templates overwriting earlier ones:
OrderDirectoryDescription
1every/Base files for all servers
2every_{type}/Type-specific (e.g., every_proxy/)
3every_{software}/Software-specific (e.g., every_paper/)
4_tagged/{tag}/For each tag assigned to the group
5{server-name}/Server-specific templates
6cache/{group}/Cached files from previous runs

​
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:

​
Configuration

Serverhost configuration via CLI parameters:
ParameterDescriptionDefault
--network-idNetwork identifierFrom env
--controller-urlController API URLplatform.simplecloud.app
--nats-urlNATS server URLplatform.simplecloud.app
--deployment-typeExecution modelocal
--port-rangeAvailable port range25565-25665
--multiplexerScreen or TmuxAuto-detect

​
Monitoring

​
Via CLI

# 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
  • Receives update notifications
  • Maintains connection with Controller
Serverhosts automatically restart servers if the Serverhost itself restarts, based on synchronization with the Controller’s state.