> ## 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.
# Server Groups
> Create and manage server groups with auto-scaling in the SimpleCloud dashboard
Groups are the core building blocks of your SimpleCloud infrastructure. A group defines a template for servers that share the same configuration, and can automatically scale based on player demand.
Looking for static servers? They've been replaced by [Persistent Servers](/en/manual/setup/persistent-servers) - single instances that keep their data between restarts and don't auto-scale.
## Understanding Groups
A **group** is a collection of servers that:
* Share the same software (Paper, Velocity, etc.) and configuration
* Can automatically scale up or down based on player count
* Are deployed to your configured server hosts
* Inherit plugins, properties, and workflows from the group configuration
There are two types of groups:
* **Server Groups** - Minecraft game servers (Spigot, Paper, Fabric, etc.)
* **Proxy Groups** - Load balancers that route players to servers (Velocity, BungeeCord)
## Creating a Group
Click **Groups** in the navigation to view your existing groups. Click the **New Group** button in the top right.
* **Name**: Enter a unique name for your group (e.g., "Lobby", "SkyWars", "BungeeCord")
* **Type**: Choose **Server** for game servers or **Proxy** for load balancers
* **Activate on creation**: Toggle on to start scaling immediately after creation
* **Software**: Choose your server software (Paper, Spigot, Purpur, Fabric, Velocity, etc.)
* **Version**: Select the Minecraft/software version
* **Custom URL**: Alternatively, provide a direct download URL for custom server JARs
* **Configurator**: Select how your server should be configured (appears for Server type)
* **Memory**: Use a preset or set custom min/max memory allocation (in MB)
* **Max Players**: Maximum players allowed per server instance
* **Scaling Mode**:
* *Slots* - Scale based on available player slots
* *Servers* - Scale based on server count
* **Start Policy**: Controls when the reconciler starts new servers
* *immediate* - Start new servers as soon as scaling rules require them (default for Server groups)
* *when\_deleted* - Only start a new server after an existing one is deleted (default for Proxy groups)
* **Min Servers**: Minimum servers to keep running at all times
* **Max Servers**: Maximum servers allowed to scale up to
* **Player Threshold**: Percentage (0-100%) at which to trigger scaling
* **Available Slots**: Number of open slots to maintain across the group
For proxy groups, configure the **Starting Port** for incoming player connections.
Search and select plugins from Modrinth to automatically install on all servers in this group. You can also add plugins later in group settings.
Review your configuration summary and click **Create Group** to finish.
## Group Status
| Status | Meaning |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Healthy** | Running normally, meeting minimum server requirements |
| **Scaling** | Currently scaling up to meet player demand |
| **Down** | No servers running - verify the group is activated, at least one server host is enabled in deployment settings, and hosts have available resources |
| **Inactive** | Group is deactivated - enable it in general settings |
| **Disabled** | Minimum servers set to 0 - increase min servers to start scaling |
## Group Settings
### General Settings
* **Active Toggle**: Enable or disable auto-scaling
* **Memory**: Adjust min/max memory allocation
* **Max Players**: Change player limit per server
* **Tags**: Add organizational tags for filtering
### Scaling Settings
Fine-tune auto-scaling behavior:
* **Scaling Mode**: Switch between Slots and Servers mode
* **Start Policy**: Controls when the reconciler starts new servers. Set to `immediate` to start servers as soon as scaling rules require them, or `when_deleted` to only replace servers after one is removed. Defaults to `immediate` for Server groups and `when_deleted` for Proxy groups.
* **Server Limits**: Adjust min/max server counts
* **Player Threshold**: When to trigger scaling (as decimal, e.g., 0.8 = 80%)
* **Available Slots**: Target number of open slots to maintain
* **Idle Time**: How long before scaling down idle servers (e.g., "3m", "1h")
### Deployment Settings
Control where servers are deployed:
* **Toggle hosts on/off** to allow or prevent deployment
* **Drag to reorder** priority (when some hosts are disabled)
* First host in the list is preferred for new server deployments
When all hosts are enabled, servers are distributed automatically. Disable some hosts to set a specific priority order.
### Blueprint Settings
Modify the underlying server template:
* View current software and version
* Change configurator settings
* Edit JVM options and runtime arguments
### Properties Settings
Add custom key-value properties to your group:
* Properties are metadata you define for your own use
* Access them in your plugins via the [Cloud API](/en/developer/controller/groups)
* Available as environment variables on servers (prefixed with `SIMPLECLOUD_`)
* Use cases: game modes, map names, custom settings for your plugins
### Workflows Settings
Automate tasks with workflows:
* **Manual Workflows**: Trigger on demand
* **On Start Workflows**: Run when servers start
* **On Stop Workflows**: Run when servers stop
### Plugins Settings
Manage plugins for the group:
* Add plugins from Modrinth, GitHub, or direct URLs
* View installed plugins with source information
* Remove plugins from the group
### Danger Zone
Permanently delete the group:
* Removes the group and its configuration
* Does not delete running servers (stop them first)
* Requires confirmation by typing the group name
## Troubleshooting
**Symptom:** Servers stay in QUEUED and never start.
**Cause:** No serverhost available or has capacity.
**Solution:**
1. Check serverhost status: `sc status serverhost`
2. Verify deployment settings allow at least one host
3. Check host memory isn't exhausted
4. Review logs: `sc logs controller`
**Symptom:** Group status is "Down" with no servers running.
**Cause:** Group not configured to start servers.
**Solution:**
1. Enable the group (Active toggle in general settings)
2. Set min servers to at least 1
3. Enable at least one serverhost in deployment settings
4. Verify host has enough free memory
**Symptom:** Players join but new servers don't start.
**Cause:** Scaling threshold not reached or max servers hit.
**Solution:**
1. Check scaling mode matches your needs (Slots vs Servers)
2. Lower the threshold (default 0.8 = 80% full)
3. Increase max servers limit
4. Verify servers are reporting player counts
**Symptom:** Servers stop while players are online.
**Cause:** Idle timeout too short or threshold misconfigured.
**Solution:**
1. Increase idle time (e.g., "5m" instead of "1m")
2. Raise the player threshold
3. Increase min servers to keep a baseline
**Symptom:** Servers stay in PREPARING and never reach STARTING.
**Cause:** Workflow failing during server setup.
**Solution:**
1. Check serverhost logs: `sc logs serverhost`
2. Verify template directories exist
3. Check disk space
4. Test plugin downloads manually
**Symptom:** Server records remain in the database after the process has terminated, causing incorrect server counts or preventing new servers from starting.
**Cause:** The server process was terminated without the controller recording the stop (e.g., a host crash or forced kill).
**Solution:**
Use the `DELETE /v0/servers/database` REST API endpoint to remove the stale record directly. See the [Servers API reference](/en/developer/api/servers#delete-server-record) for details.
This only removes the database row. It does not stop any running process or trigger cleanup workflows.