Guide

Agent-based workflow

The agent runs on each game host and periodically syncs host and instance state with the control plane. The platform responds with the desired instance configuration.

1. Installation

Install the agent runtime on each host where game servers should run.

# Example host setup
apt update
apt install -y docker.io
mkdir -p /opt/gsm-agent

2. Configuration

Configure the control-plane URL and token for the host.

# Example environment variables
GSM_ADMIN_URL=https://your-gsm-domain.example
GSM_AGENT_TOKEN=replace-with-issued-token
GSM_AGENT_HEARTBEAT_PATH=/api/agent/heartbeat/
GSM_AGENT_INTERVAL_SECONDS=30

3. Heartbeat flow

The agent first registers itself at /api/agent/register/, then sends regular heartbeat requests to /api/agent/heartbeat/ with bearer authentication and receives desired instance state in response.

4. End-to-end onboarding workflow

1. Create a Host in the Django admin (hostname, owner, optional ip_address).
2. Create a GameDefinition with image and defaults (default_env, default_ports, default_volumes).
3. Create/open the host AgentToken, rotate it, and copy the plaintext token immediately.
4. Create a GameServerInstance for the host+definition and set desired_state (usually running).
5. Start gsm-agent on the host with --admin-url and --token.
6. Verify Host.last_seen updates and the matching Docker container is created/stopped based on desired state.

# Example local run on host
python gsm_agent.py \
  run \
  --admin-url "$GSM_ADMIN_URL" \
  --token "$GSM_AGENT_TOKEN"

5. Operations checklist

• Ensure outbound network access from host to control plane.
• Rotate agent tokens periodically.
• Monitor heartbeat freshness and host status.
• Apply server template updates through admin before rollout.