Skip to main content

​
What the Controller Does

The Controller coordinates your SimpleCloud infrastructure. It tracks what servers should be running, decides when to start or stop them based on scaling rules, and tells serverhosts what to do via NATS messaging.

​
When You Need to Know This

Understanding the Controller helps when you’re:
  • Debugging server startup issues - Why isn’t my server starting? Is it queued? Is the reconciler running?
  • Setting up high availability - Running multiple controllers requires understanding leader election
  • Understanding scaling behavior - Why did a server start or stop? How does the reconciliation loop decide?

​
State Management

The Controller maintains the authoritative state of your network:
EntityDescription
NetworksRegistered Minecraft networks with credentials
BlueprintsServer configuration templates
GroupsScalable server collections with auto-scaling rules
ServersRunning server instances and their status
Persistent ServersLong-running dedicated servers
ServerhostsConnected execution agents
PluginsPlugin definitions and assignments

​
Reconciliation Loop

Every 5 seconds, the Controller:
  1. Compares desired state (your configuration) with actual state (running servers)
  2. Determines which servers need to start or stop
  3. Selects serverhosts based on capacity and preferences
  4. Sends start/stop commands via NATS
This loop ensures your infrastructure matches your configuration, even after failures or manual changes.

​
Auto-Scaling

​
Slot-Based Scaling

Scale based on total available player slots: 
scaling:
  mode: SLOTS
  min_servers: 1
  max_servers: 5
  player_threshold: 0.8  # Scale up when 80% full

​
Server-Based Scaling

Maintain a fixed number of servers: 
scaling:
  mode: SERVER
  min_servers: 2
  max_servers: 2

​
High Availability

For production deployments, you can run multiple Controller instances:
  • Leader election uses database-backed consensus with a 30-second lease
  • Only the leader performs network assignments and reconciliation
  • All instances can serve API requests
  • Automatic failover if the leader becomes unavailable

​
Infrastructure Requirements

ComponentPurposeRequired
PostgreSQLState persistenceYes
NATSServerhost messagingYes
Valkey/RedisMetrics cachingOptional
ClickHouseLog storageOptional

​
Troubleshooting

Symptom: Controller process exits immediately or fails to bind to port.Solution:
  1. Check PostgreSQL is running: systemctl status postgresql
  2. Verify NATS is reachable: nc -zv localhost 4222
  3. Check logs: sc logs controller
  4. Ensure port 1337 is free: lsof -i :1337
Symptom: Servers stay in QUEUED state and never start.Cause: No serverhost available to run the server.Solution:
  1. Check serverhost status: sc status serverhost
  2. Verify hosts have available memory
  3. Check deployment settings allow the serverhost
  4. Review logs: sc logs controller
Symptom: Servers don’t scale up when players join or down when empty.Cause: Reconciliation not triggering or metrics not reported.Solution:
  1. Verify Controller is leader: look for “became leader” in logs
  2. Check group scaling config (min/max servers, threshold)
  3. Ensure servers report player counts
  4. Check reconciliation logs for errors
Symptom: API calls fail with authentication errors.Solution:
  1. Verify X-Network-ID header matches your network
  2. Verify X-Network-Secret header is correct
  3. Check credentials in secrets/ directory
Symptom: API calls fail with internal server error.Solution:
  1. Check Controller logs for stack traces
  2. Verify PostgreSQL connectivity
  3. Check disk space and memory

​
CLI Access

# Check controller status
sc status

# View controller logs
sc logs controller

# Attach to controller console
sc attach controller
The Controller must be running for new servers to start. Existing servers continue running if the Controller temporarily goes offline.