GenericServer — Pterodactyl Server Control Reference

GenericServer is the base class for all HungerLib server objects. It wraps the Pterodactyl Client API for a single server identifier and provides resource monitoring, power control, file management, backup and database operations, startup variable configuration, and schedule management. For Minecraft-specific functionality — TPS, player queries, and console commands via HungerBridge — see MinecraftServer, which extends this class.

from hungerlib import Panel
from hungerlib.servers import GenericServer

panel = Panel("production", "https://panel.example.com", "ptlc_xxxx")
server = GenericServer("my-server", panel, "a1b2c3d4")

server.start()
print(server.getRAM())  # e.g. 512.34 (MB)

Constructor

GenericServer(name: str, panel: Panel, server_id: str)

name

str

required

A human-readable label for this server. Used in logging and display only.

panel

Panel

required

An authenticated Panel instance that this server will use for all API calls.

server_id

str

required

The Pterodactyl server identifier (short UUID), found in the panel URL or API response.

After construction, self._cached_resources is None. It is populated on the first call to resources() or refresh().

Resources

These methods read live or cached resource data from the Pterodactyl API.

`refresh()`

server.refresh() -> dict

Forces a fresh fetch of the server’s resource metrics from GET /api/client/servers/{id}/resources, caches the result in self._cached_resources, and returns it. Returns dict containing raw resource fields from the Pterodactyl API (memory_bytes, cpu_absolute, disk_bytes, network_rx_bytes, network_tx_bytes, uptime).

`resources()`

server.resources() -> dict

Returns the cached resource dict if available; otherwise calls refresh() first. Returns dict — same shape as refresh().

`getRAM()`

server.getRAM(rounding: int = 2, gb: bool = False) -> float | None

rounding

int

default:"2"

Number of decimal places to round the result to.

bool

default:"False"

When True, returns the value in gigabytes. When False (default), returns megabytes.

Returns float | None — current RAM usage in MB (or GB if gb=True), or None if the metric is unavailable.

`getCPU()`

server.getCPU(rounding: int = 2) -> float | None

rounding

int

default:"2"

Number of decimal places to round the result to.

Returns float | None — current CPU usage as an absolute percentage (e.g. 45.67), or None if unavailable.

`getDisk()`

server.getDisk(rounding: int = 2, gb: bool = False) -> float | None

rounding

int

default:"2"

Number of decimal places to round the result to.

bool

default:"False"

When True, returns the value in gigabytes. When False, returns megabytes.

Returns float | None — current disk usage in MB or GB, or None if unavailable.

`getNetworkIn()`

server.getNetworkIn(rounding: int = 2, gb: bool = False) -> float | None

rounding

int

default:"2"

Number of decimal places to round the result to.

bool

default:"False"

When True, returns the value in gigabytes. When False, returns megabytes.

Returns float | None — cumulative inbound network usage in MB or GB, or None if unavailable.

`getNetworkOut()`

server.getNetworkOut(rounding: int = 2, gb: bool = False) -> float | None

rounding

int

default:"2"

Number of decimal places to round the result to.

bool

default:"False"

When True, returns the value in gigabytes. When False, returns megabytes.

Returns float | None — cumulative outbound network usage in MB or GB, or None if unavailable.

`getUptime()`

server.getUptime(formatted: bool = False) -> int | str | None

formatted

bool

default:"False"

When False (default), returns uptime as raw seconds. When True, returns a human-readable string such as "2h 15m", "45m 30s", or "12s".

Returns int (seconds) when formatted=False, str when formatted=True, or None if the server has not reported an uptime value.

print(server.getUptime())          # 8130
print(server.getUptime(True))      # "2h 15m"

Status

`getStatus()`

server.getStatus() -> str

Fetches the server’s current lifecycle state directly from the API (not the cache). Returns str — Pterodactyl state string, typically one of "running", "offline", "starting", or "stopping".

`isOnline()`

server.isOnline() -> bool

Returns True if getStatus() returns "running", False otherwise.

`isOffline()`

server.isOffline() -> bool

Returns True if getStatus() returns "offline", False otherwise.

Power

`powerAction()`

server.powerAction(action: str) -> tuple

Sends a power signal to the server via POST /api/client/servers/{id}/power.

action

str

required

The power signal to send. Must be one of "start", "stop", "restart", or "kill".

Returns tuple — (status_code, response_body). Raises ValueError if action is not one of the four valid values.

`start()`

server.start() -> tuple

Shortcut for powerAction("start"). Sends the start signal to a stopped server. Returns tuple — (status_code, response_body).

`stop()`

server.stop() -> tuple

Shortcut for powerAction("stop"). Sends a graceful stop signal. Returns tuple — (status_code, response_body).

`restart()`

server.restart() -> tuple

Shortcut for powerAction("restart"). Sends a restart signal. Returns tuple — (status_code, response_body).

`kill()`

server.kill() -> tuple

Shortcut for powerAction("kill"). Immediately terminates the server process without a graceful shutdown. Returns tuple — (status_code, response_body).

Files

All file methods delegate to panel.files (FileManagerAPI).

`listFiles()`

server.listFiles(directory: str = "/") -> requests.Response

`downloadFile()`

server.downloadFile(path: str) -> requests.Response

path

str

required

Server-relative path to the file, e.g. "/server.properties".

Returns requests.Response containing a signed download URL.

`uploadFile()`

server.uploadFile(directory: str, file_data) -> requests.Response

`deleteFiles()`

server.deleteFiles(root: str, files) -> requests.Response

root

str

required

Root directory for the operation.

files

list[str]

required

List of filenames (relative to root) to delete.

Returns requests.Response.

`renameFiles()`

server.renameFiles(root: str, files) -> requests.Response

root

str

required

Root directory for the operation.

files

list[dict]

required

List of rename objects with "from" and "to" keys.

Returns requests.Response.

`copyFiles()`

server.copyFiles(root: str, files) -> requests.Response

root

str

required

Root directory for the operation.

files

list[str]

required

List of file paths to copy.

Returns requests.Response.

`moveFiles()`

server.moveFiles(root: str, files) -> requests.Response

root

str

required

Root directory for the operation.

files

list[dict]

required

List of move objects with "from" and "to" keys.

Returns requests.Response.

`createFolder()`

server.createFolder(directory: str, name: str) -> requests.Response

`compress()`

server.compress(root: str, files) -> requests.Response

root

str

required

Root directory for the operation.

files

list[str]

required

List of file or directory names (relative to root) to include in the archive.

Returns requests.Response.

`decompress()`

server.decompress(file_path: str) -> requests.Response

file_path

str

required

Server-relative path to the archive to decompress.

Returns requests.Response.

Backups

`listBackups()`

server.listBackups() -> requests.Response

Returns requests.Response containing the list of all backups for this server.

`createBackup()`

server.createBackup(name: str) -> requests.Response

name

str

required

Display name for the new backup.

Returns requests.Response.

`deleteBackup()`

server.deleteBackup(backup_id: int) -> requests.Response

backup_id

int

required

Numeric ID of the backup to delete.

Returns requests.Response.

`downloadBackup()`

server.downloadBackup(backup_id: int) -> requests.Response

backup_id

int

required

Numeric ID of the backup to download.

Returns requests.Response containing a signed download URL.

Databases

`listDatabases()`

server.listDatabases() -> requests.Response

Returns requests.Response containing all databases attached to this server.

`createDatabase()`

server.createDatabase(name: str, remote: str = "%", host=None) -> requests.Response

name

str

required

Name for the new database.

remote

str

default:"%"

Remote host pattern that is allowed to connect. Defaults to "%" (any host).

host

str | None

default:"None"

Optional database host override. When None, the panel’s default database host is used.

Returns requests.Response.

`rotateDatabasePassword()`

server.rotateDatabasePassword(db_id: str) -> requests.Response

db_id

str

required

The database identifier string as returned by listDatabases().

Returns requests.Response containing the new password.

`deleteDatabase()`

server.deleteDatabase(db_id: str) -> requests.Response

db_id

str

required

The database identifier string to delete.

Returns requests.Response.

Startup

`getStartupVariables()`

server.getStartupVariables() -> requests.Response

Returns requests.Response containing all startup environment variables defined for this server.

`updateStartupVariable()`

server.updateStartupVariable(key: str, value: str) -> requests.Response

key

str

required

The environment variable name, e.g. "SERVER_JARFILE".

value

str

required

The new value to set.

Returns requests.Response.

Schedules

`listSchedules()`

server.listSchedules() -> requests.Response

Returns requests.Response containing all schedules for this server.

`createSchedule()`

server.createSchedule(payload: str) -> requests.Response

payload

str

required

Schedule creation payload as expected by the Pterodactyl API, including cron fields (minute, hour, day_of_month, month, day_of_week) and optionally name, is_active, and only_when_online.

Returns requests.Response.

`updateSchedule()`

server.updateSchedule(schedule_id: str, payload: str) -> requests.Response

schedule_id

str

required

The schedule identifier to update.

payload

str

required

Payload of fields to update on the schedule.

Returns requests.Response.

`deleteSchedule()`

server.deleteSchedule(schedule_id: str) -> requests.Response

schedule_id

str

required

The schedule identifier to delete.

Returns requests.Response.

`runSchedule()`

server.runSchedule(schedule_id: str) -> requests.Response

Immediately triggers a schedule regardless of its cron timing.

schedule_id

str

required

The schedule identifier to run.

Returns requests.Response.

`enableSchedule()`

server.enableSchedule(schedule_id: str) -> requests.Response

Convenience method that calls updateSchedule(schedule_id, {"is_active": True}).

schedule_id

str

required

The schedule identifier to enable.

Returns requests.Response.

`disableSchedule()`

server.disableSchedule(schedule_id: str) -> requests.Response

Convenience method that calls updateSchedule(schedule_id, {"is_active": False}).

schedule_id

str

required

The schedule identifier to disable.

Returns requests.Response.

`getSchedule()`

server.getSchedule(schedule_id: int) -> dict | None

Fetches the full schedule list and returns the matching schedule as a normalised dict. Returns None if no schedule with the given ID is found.

schedule_id

int

required

Numeric ID of the schedule to retrieve.

Returns dict | None with the following keys:

int

Numeric schedule identifier.

name

str

Display name of the schedule.

description

str

Optional description set on the schedule.

is_active

bool

Whether the schedule is currently enabled.

cron

dict

Raw cron object from the API.

minute

str

Cron minute field, e.g. "*/5".

hour

str

Cron hour field, e.g. "*".

day_of_month

str

Cron day-of-month field.

month

str

Cron month field.

day_of_week

str

Cron day-of-week field.

next_run_at

str

ISO 8601 timestamp for the next scheduled run.

last_run_at

str

ISO 8601 timestamp of the most recent run, or null if never run.

only_when_online

bool

When true, the schedule only runs while the server is in the running state.

is_processing

bool

Whether the schedule is currently executing.

created_at

str

ISO 8601 creation timestamp.

updated_at

str

ISO 8601 last-updated timestamp.

tasks

list

List of task objects belonging to this schedule, sourced from the relationships.tasks.data array in the Pterodactyl response.

sched = server.getSchedule(3)
if sched:
    print(sched["name"], sched["next_run_at"])

Classes

Panel API Modules

Utilities & Exceptions

Documentation Index

​Constructor

​Resources

​refresh()

​resources()

​getRAM()

​getCPU()

​getDisk()

​getNetworkIn()

​getNetworkOut()

​getUptime()

​Status

​getStatus()

​isOnline()

​isOffline()

​Power

​powerAction()

​start()

​stop()

​restart()

​kill()

​Files

​listFiles()

​downloadFile()

​uploadFile()

​deleteFiles()

​renameFiles()

​copyFiles()

​moveFiles()

​createFolder()

​compress()

​decompress()

​Backups

​listBackups()

​createBackup()

​deleteBackup()

​downloadBackup()

​Databases

​listDatabases()

​createDatabase()

​rotateDatabasePassword()

​deleteDatabase()

​Startup

​getStartupVariables()

​updateStartupVariable()

​Schedules

​listSchedules()

​createSchedule()

​updateSchedule()

​deleteSchedule()

​runSchedule()

​enableSchedule()

​disableSchedule()

​getSchedule()

Build docs developers (and LLMs) love

Constructor

Resources

`refresh()`

`resources()`

`getRAM()`

`getCPU()`

`getDisk()`

`getNetworkIn()`

`getNetworkOut()`

`getUptime()`

Status

`getStatus()`

`isOnline()`

`isOffline()`

Power

`powerAction()`

`start()`

`stop()`

`restart()`

`kill()`

Files

`listFiles()`

`downloadFile()`

`uploadFile()`

`deleteFiles()`

`renameFiles()`

`copyFiles()`

`moveFiles()`

`createFolder()`

`compress()`

`decompress()`

Backups

`listBackups()`

`createBackup()`

`deleteBackup()`

`downloadBackup()`

Databases

`listDatabases()`

`createDatabase()`

`rotateDatabasePassword()`

`deleteDatabase()`

Startup

`getStartupVariables()`

`updateStartupVariable()`

Schedules

`listSchedules()`

`createSchedule()`

`updateSchedule()`

`deleteSchedule()`

`runSchedule()`

`enableSchedule()`

`disableSchedule()`

`getSchedule()`