Go Agent Overview

The PixlPay Go Agent is a standalone delivery agent that connects to game servers via RCON. It's the recommended integration method for games that don't have native plugin support.

Features

• Automatic polling for pending deliveries
• RCON command execution
• Support for purchases, refunds, and chargebacks
• Dual-secret authentication
• Command history and delivery logging
• Interactive CLI mode for debugging
• Automatic reconnection with exponential backoff
• Runs as a background service

Supported Games

Game	Status	Setup Guide
Project Zomboid	Fully Supported	Full Guide
Minecraft	Planned	Coming Soon
ARK: Survival Evolved	Planned	Coming Soon

Download

Download the latest release for your platform:

Platform	Download
Windows	pixlpay-agent.exe
Linux	pixlpay-agent
macOS (Intel)	pixlpay-agent
macOS (Apple Silicon)	pixlpay-agent

Downloads are also available from your Pixlpay Dashboard under Settings > Game Servers > Downloads.

Quick Start

1. Download the Agent

Get the appropriate version for your server's operating system.

2. Create Configuration

Create a pixlpay-config.json file in the same directory:

{
    "platform_url": "https://api.pixlpay.net",
    "store_secret": "YOUR_STORE_SECRET",
    "server_secret": "YOUR_SERVER_SECRET",
    "game_type": "project_zomboid",
    "rcon_host": "127.0.0.1",
    "rcon_port": 27015,
    "rcon_password": "YOUR_RCON_PASSWORD",
    "debug_mode": false
}

3. Run the Agent

# Windows
./store-agent.exe

# Linux
./store-agent-linux

Configuration Options

Field	Required	Description
platform_url	Yes	API endpoint (https://api.pixlpay.net)
store_secret	Yes	Your store's API key from dashboard
server_secret	Yes	This server's unique secret from dashboard
game_type	Yes	Game identifier (e.g., project_zomboid)
rcon_host	Yes	RCON server address (usually 127.0.0.1)
rcon_port	Yes	RCON port from your game server config
rcon_password	Yes	RCON password from your game server config
debug_mode	No	Enable verbose logging for troubleshooting (default: false)
dev_mode	No	Use dev_api_url instead of production API (default: false)
dev_api_url	No	Custom API URL when dev_mode is enabled

Command Line Options

# Show help
./store-agent.exe -help

# Use custom config file
./store-agent.exe -config=/path/to/pixlpay-config.json

# Interactive mode (with admin commands)
./store-agent.exe -interactive

# Show version
./store-agent.exe -version

Interactive Mode

Run with -interactive to access admin commands:

Command	Description
status	Show agent status (version, secrets, API URL, RCON status, polling times)
poll	Force immediate poll for pending commands
queue	Show pending deliveries waiting for offline players
history [N]	Show last N executed commands (default: 10)
test	Test API connection and display server info
debug	Toggle debug mode on/off
heartbeat	Send heartbeat to API and display response
help	Show all available commands
quit / exit	Stop the agent gracefully

Example Session

========================================
     PixlPay Store Agent v1.0.0
========================================
Game Type:    project_zomboid
RCON Target:  127.0.0.1:27015
API Endpoint: https://api.pixlpay.net
========================================
Connecting to RCON at 127.0.0.1:27015...
RCON connection established!
Agent ready! Polling every 60s, heartbeat every 2m0s

> test
Testing API connection...
Connection successful! API returned status 200.
Server recognized: My PZ Server (ID: 123)
Pending commands: 0

> status
Agent Status:
  - RCON: Connected
  - API: Healthy
  - Last Poll: 5 seconds ago
  - Commands Executed: 42
  - Pending Queue: 0

Logs

The agent writes logs to the logs/ directory (auto-created on first run):

Log File	Contents
pixlpay-general_YYYY-MM-DD.log	All events (comprehensive log for debugging)
pixlpay-deliveries_YYYY-MM-DD.log	Successful deliveries and startup/shutdown events
pixlpay-errors_YYYY-MM-DD.log	Errors and warnings only

Log files rotate automatically at midnight each day.

Log Format

Each log entry includes:

[YYYY-MM-DD HH:MM:SS] [LEVEL] Message

Log Levels

Level	Description	Written To
[INFO]	General information	Console + General log
[DEBUG]	Verbose debug info (requires debug_mode: true)	Console + General log
[WARN]	Warnings	Console + General log + Error log
[ERROR]	Errors	Console + General log + Error log
[DELIVERY]	Successful deliveries	Console + General log + Delivery log
[STARTUP]	Agent startup	General log + Delivery log
[SHUTDOWN]	Agent shutdown	General log + Delivery log

Running as a Service

Windows (Using NSSM)

NSSM (Non-Sucking Service Manager) is recommended for Windows:

# Download NSSM from https://nssm.cc/download
# Open Command Prompt as Administrator

nssm install PixlPayAgent "C:\path\to\store-agent.exe"
nssm set PixlPayAgent AppDirectory "C:\path\to"
nssm set PixlPayAgent DisplayName "PixlPay Delivery Agent"
nssm set PixlPayAgent Description "Automatic delivery agent for game servers"
nssm set PixlPayAgent Start SERVICE_AUTO_START
nssm start PixlPayAgent

Manage the service:

nssm status PixlPayAgent  # Check status
nssm stop PixlPayAgent    # Stop service
nssm restart PixlPayAgent # Restart service
nssm remove PixlPayAgent  # Remove service

Linux (Using systemd)

Create /etc/systemd/system/pixlpay-agent.service:

[Unit]
Description=PixlPay Delivery Agent
After=network.target

[Service]
Type=simple
User=gameserver
WorkingDirectory=/home/gameserver/pixlpay
ExecStart=/home/gameserver/pixlpay/store-agent-linux
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable pixlpay-agent
sudo systemctl start pixlpay-agent

Manage the service:

sudo systemctl status pixlpay-agent   # Check status
sudo systemctl stop pixlpay-agent     # Stop service
sudo systemctl restart pixlpay-agent  # Restart service
journalctl -u pixlpay-agent -f        # Follow logs

Directory Structure

Recommended setup:

/home/gameserver/pixlpay/
├── store-agent-linux       # The agent executable
├── pixlpay-config.json     # Your configuration
├── data/
│   └── agent_data.json     # Persistent data (auto-created)
└── logs/
    ├── pixlpay-general_2025-01-15.log
    ├── pixlpay-deliveries_2025-01-15.log
    └── pixlpay-errors_2025-01-15.log

Timing Constants

These values are hardcoded and not user-configurable:

Constant	Value	Purpose
Poll Interval	60 seconds	Time between API polls for pending commands
Heartbeat Interval	120 seconds (2 minutes)	Time between heartbeat status updates to API
Initial Retry Delay	5 seconds	Initial RCON connection retry delay
Max Retry Delay	5 minutes	Maximum RCON retry delay (exponential backoff cap)
Max Retries	3	Maximum command execution retries before failure
Request Timeout	10 seconds	HTTP request timeout for API calls

Notification Types

The agent handles three notification types:

Type	Description	Execution
purchase_notification	Player purchased item	Execute immediately or queue
refund_notification	Refund issued	Execute immediately
chargeback_notification	Payment disputed	Execute immediately

Security Considerations

1. Run as non-root user - Create a dedicated user for the agent
2. Secure config file - Restrict permissions on pixlpay-config.json
3. Use localhost for RCON - If running on same machine, use 127.0.0.1
4. Strong RCON password - Use at least 16 random characters
5. Never commit config - Add pixlpay-config.json to .gitignore

Game-Specific Guides

• Project Zomboid Setup Guide - Complete PZ integration

Troubleshooting

See the Troubleshooting Guide for common issues and solutions.