Startup Configuration

Startup variables control how your server starts, including game versions, memory limits, and application-specific settings.

Get Startup Variables

Retrieve all startup variables for a server.

curl -X GET "https://panel.example.com/api/client/servers/{server}/startup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

server

string

required

The server identifier

Response

{
  "object": "list",
  "data": [
    {
      "object": "egg_variable",
      "attributes": {
        "name": "Server Version",
        "description": "The version of Minecraft to install. Use 'latest' for the latest version.",
        "env_variable": "MINECRAFT_VERSION",
        "default_value": "latest",
        "server_value": "1.20.4",
        "is_editable": true,
        "rules": "required|string|max:20"
      }
    },
    {
      "object": "egg_variable",
      "attributes": {
        "name": "Server Type",
        "description": "The type of server to install (vanilla, paper, forge, etc.)",
        "env_variable": "SERVER_TYPE",
        "default_value": "paper",
        "server_value": "paper",
        "is_editable": true,
        "rules": "required|string|in:vanilla,paper,purpur,forge,fabric"
      }
    },
    {
      "object": "egg_variable",
      "attributes": {
        "name": "Build Number",
        "description": "The build number for Paper servers. Use 'latest' for the newest build.",
        "env_variable": "BUILD_NUMBER",
        "default_value": "latest",
        "server_value": "latest",
        "is_editable": true,
        "rules": "required|string"
      }
    }
  ],
  "meta": {
    "startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
    "raw_startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
    "docker_images": {
      "Java 17": "ghcr.io/pterodactyl/yolks:java_17",
      "Java 21": "ghcr.io/pterodactyl/yolks:java_21",
      "Java 8": "ghcr.io/pterodactyl/yolks:java_8"
    }
  }
}

name

string

Human-readable variable name

description

string

Description of what the variable controls

env_variable

string

Environment variable name (used for updates)

default_value

string

Default value from the egg configuration

server_value

string

Current value set for this server

is_editable

boolean

Whether users can modify this variable

rules

string

Laravel validation rules for the variable

Metadata Fields

meta.startup_command

string

The startup command with variables replaced with actual values

meta.raw_startup_command

string

The raw startup command template with variable placeholders

meta.docker_images

object

Available Docker images for the server (read-only via client API)

Update Startup Variable

Update a single startup variable.

curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MINECRAFT_VERSION",
    "value": "1.20.4"
  }'

key

string

required

The environment variable name (e.g., MINECRAFT_VERSION)

value

string

required

The new value for the variable

Response

{
  "object": "egg_variable",
  "attributes": {
    "name": "Server Version",
    "description": "The version of Minecraft to install. Use 'latest' for the latest version.",
    "env_variable": "MINECRAFT_VERSION",
    "default_value": "latest",
    "server_value": "1.20.4",
    "is_editable": true,
    "rules": "required|string|max:20"
  },
  "meta": {
    "startup_command": "java -Xms128M -Xmx2048M -jar server.jar",
    "raw_startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}"
  }
}

The updated startup command is returned in the metadata. Most variable changes require a server restart to take effect.

Variable Validation

Variables are validated according to their rules field. Common validation rules:

required - Value cannot be empty
string - Must be a string
integer - Must be an integer
boolean - Must be true/false or 1/0
in:value1,value2 - Must be one of the listed values
max:n - Maximum length or value
min:n - Minimum length or value
regex:pattern - Must match regex pattern

Validation Examples

# Valid: Version number
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MINECRAFT_VERSION",
    "value": "1.20.4"
  }'

# Valid: Latest version
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MINECRAFT_VERSION",
    "value": "latest"
  }'

# Invalid: Empty value (if required)
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MINECRAFT_VERSION",
    "value": ""
  }'
# Error: The value field is required.

Read-Only Variables

Some variables are marked as is_editable: false. These cannot be modified through the client API:

{
  "object": "egg_variable",
  "attributes": {
    "name": "Server Memory",
    "env_variable": "SERVER_MEMORY",
    "server_value": "2048",
    "is_editable": false
  }
}

Attempting to update a read-only variable will result in an error:

{
  "errors": [
    {
      "code": "BadRequestHttpException",
      "status": "400",
      "detail": "The environment variable you are trying to edit is read-only."
    }
  ]
}

Common Variables by Game

Minecraft (Java Edition)

# Server version
"MINECRAFT_VERSION": "1.20.4"         # or "latest"

# Server type
"SERVER_TYPE": "paper"                # vanilla, paper, purpur, forge, fabric, spigot

# Build number (for Paper/Purpur)
"BUILD_NUMBER": "latest"              # or specific build number

# Server JAR file
"SERVER_JARFILE": "server.jar"

Minecraft (Bedrock Edition)

# Server version
"BEDROCK_VERSION": "latest"           # or specific version like "1.20.50"

# Server name
"SERVER_NAME": "My Bedrock Server"

# Gamemode
"GAMEMODE": "survival"                # survival, creative, adventure

# Difficulty  
"DIFFICULTY": "normal"                # peaceful, easy, normal, hard

Rust

# Server name
"SERVER_NAME": "My Rust Server"

# Max players
"MAX_PLAYERS": "100"

# World size
"WORLD_SIZE": "3000"                  # Map size in meters

# World seed
"WORLD_SEED": "12345"                 # Procedural generation seed

# RCON password
"RCON_PASSWORD": "changeme"

Valheim

# Server name
"SERVER_NAME": "My Valheim Server"

# World name
"WORLD_NAME": "Dedicated"

# Password
"SERVER_PASSWORD": "secret123"

# Public server
"PUBLIC_SERVER": "1"                  # 0 = private, 1 = public

Counter-Strike 2

# Server name
"SERVER_NAME": "My CS2 Server"

# Game mode
"GAME_MODE": "0"                      # 0=casual, 1=competitive

# Map group
"MAP_GROUP": "mg_active"              # Map rotation group

# Start map  
"START_MAP": "de_dust2"

# RCON password
"RCON_PASSWORD": "changeme"

Startup Command Variables

Variables are used in the startup command template:

# Template
java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}

# After substitution (with SERVER_MEMORY=2048, SERVER_JARFILE=server.jar)
java -Xms128M -Xmx2048M -jar server.jar

Common template variables:

{{SERVER_MEMORY}} - Memory limit in MB
{{SERVER_PORT}} - Primary server port
{{SERVER_IP}} - Server IP address
Any custom egg variable (e.g., {{MINECRAFT_VERSION}})

Best Practices

Update Variables Before Installation

For new servers, update variables before first start:

# Set Minecraft version
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "MINECRAFT_VERSION", "value": "1.20.4"}'

# Set server type
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "SERVER_TYPE", "value": "paper"}'

# Start server
curl -X POST "https://panel.example.com/api/client/servers/{server}/power" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "start"}'

Restart After Changes

Most variable changes require a server restart:

# Update variable
curl -X PUT "https://panel.example.com/api/client/servers/{server}/startup/variable" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "MINECRAFT_VERSION", "value": "1.20.6"}'

# Restart server to apply changes
curl -X POST "https://panel.example.com/api/client/servers/{server}/power" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "restart"}'

Validate Before Updating

Check the current value and rules before updating:

# Get all variables
curl -X GET "https://panel.example.com/api/client/servers/{server}/startup" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[] | select(.attributes.env_variable == "MINECRAFT_VERSION")'

Overview

Application API

Client API

Get Startup Variables

Response

Metadata Fields

Update Startup Variable

Response

Variable Validation

Validation Examples

Read-Only Variables

Common Variables by Game

Minecraft (Java Edition)

Minecraft (Bedrock Edition)

Rust

Valheim

Counter-Strike 2

Startup Command Variables

Best Practices

Update Variables Before Installation

Restart After Changes

Validate Before Updating

Build docs developers (and LLMs) love

Overview

Application API

Client API

​Get Startup Variables

​Response

​Metadata Fields

​Update Startup Variable

​Response

​Variable Validation

​Validation Examples

​Read-Only Variables

​Common Variables by Game

​Minecraft (Java Edition)

​Minecraft (Bedrock Edition)

​Rust

​Valheim

​Counter-Strike 2

​Startup Command Variables

​Best Practices

​Update Variables Before Installation

​Restart After Changes

​Validate Before Updating

Build docs developers (and LLMs) love

Get Startup Variables

Response

Metadata Fields

Update Startup Variable

Response

Variable Validation

Validation Examples

Read-Only Variables

Common Variables by Game

Minecraft (Java Edition)

Minecraft (Bedrock Edition)

Rust

Valheim

Counter-Strike 2

Startup Command Variables

Best Practices

Update Variables Before Installation

Restart After Changes

Validate Before Updating