Extension Reference

Introduction

This page lists everything available to extensions. For a guided introduction, see Building Extensions.

Manifest

The extension.json file supports these keys:

Each entry in ui.screens supports these keys:

Screen URLs use these roots, followed by the screen's path:

Compatibility is checked before activation. Dependencies load first; incompatible packages and dependency cycles are skipped. Disable dependents before disabling or removing a required extension.

Artisan Commands

Backend

Provider Methods

The Pterodactyl\Extensions\ExtensionProvider class offers these protected methods:

Route Helpers

Each route helper takes the path to a route file, and loads it under a prefix with the Panel's middleware. The registerApiRoutes method calls the first four for you.

Route names are prefixed with extensions.{id}., followed by client., server., admin., application., or web.. The path /api/admin/extensions/{id}/settings is reserved for the Panel.

Settings

ExtensionSettingDefinition::make($key, $input, $default, $rules) defines one setting. It supports these methods:

The admin form validates submitted values against their definitions. Updates may include only the settings being changed. Values must be JSON scalars or arrays, nested at most ten levels deep. A password control alone does not enable encryption.

The store returned by settings() supports:

Global, user, and server scopes are separate. Deleting a user or server deletes its scoped settings. ExtensionSettings::preload($stores) loads several stores together. An ExtensionSettingsDefinition also supports forUser and forServer.

Permissions

Register extension permissions with registerPermissions($description, ['read' => 'Read notes.']). The key becomes ext.{id}.read and appears in the server subuser editor. Use it with $user->can(...), the SDK permission hooks, and a server screen's permission list. A wildcard such as ext.server-notes.* covers only that extension. Server owners and root administrators pass every permission check.

You may also use these core permission names:

Events

The Panel dispatches these events from the Pterodactyl\Events\Extensions namespace. Each one has a public $manifest property, except where noted.

Server Operation Events

listenToServerOperations receives Pterodactyl\Events\Server\OperationCompleted:

These properties are read-only. Events dispatch after the database transaction commits. Provisioning is reported only after Wings accepts creation. Listener failures are recorded against the extension.

Job Progress

Pterodactyl\Services\Extensions\ExtensionJobProgress supports:

Status is running, completed, or failed. Finished snapshots cannot be updated. Each update increases sequence. The frontend payload contains id, extension, status, percent, message, sequence, and updated_at.

Both endpoints require authentication. User-only jobs and server jobs without a permission are private to their creator and root administrators. Server jobs with a permission require current server access and that permission, which must belong to the same extension. Disabled extensions and missing, expired, or inaccessible jobs return 404. Responses are not cached by the browser.

Workers and web requests must share a cache store. Retention is controlled by extensions.progress_retention_seconds, defaulting to 3,600 seconds after the last update. Keep durable results or audit records separately.

Frontend SDK

Import runtime components and hooks from @pterodactyl/sdk. The Panel provides them through its import map, so they are not bundled into your extension. Build, testing, and generated-client helpers use the subpaths listed below.

Use definePterodactylExtension({ setup }) for an entry definition, or defineConfiguredExtension(parseConfig, { setup }) with generated configuration and screen types. setup is synchronous, and its registrations become visible together after it finishes successfully.

Setup Context

The setup function receives an object with these properties:

Component Replacements

The component catalog is exported as COMPONENT_NAMES. ReplacementProps<Name> contains a read-only model, the native Default component, and parts. Default accepts className and a partial parts map. Each part receives { model }, typed by ComponentPartProps<Name>.

ServerCardModel has identifier, uuid, name, nullable description, nullable address, and state. Its state is one of:

• { kind: 'loading' }.
• { kind: 'unavailable', reason }, where reason is suspended, connection-error, maintenance, transferring, installing, restoring-backup, or unavailable.
• { kind: 'ready', power, cpu, memory, disk }. power is offline, stopped, starting, running, or stopping. Each metric has numeric value, numeric limit, and boolean alarm. CPU values are percentages; memory and disk values are bytes. A zero limit means unlimited.

FileDetailsModel has name, kind, size, and modifiedAt. kind is file, directory, archive, or symlink. Size is in bytes; modifiedAt is the API timestamp string.

The supported areas are non-interactive content inside core links. The Panel retains polling, permission-aware navigation, accessible link names, selection, menus, and modals. The native server-card identity part renders dashboard.serverRow.name.after; other server-row slots remain in the core frame.

Each declared name must have exactly one implementation in synchronous setup. Unknown names, undeclared registrations, duplicate registrations, or missing implementations fail the extension's atomic setup. Lazy importers return a module with a default React component. Use the importer form for lazy views rather than registering React.lazy directly.

A component has one enabled owner. Conflicting enable and update requests fail before activation. Enabling and disabling the extension controls its replacements; reload open browser sessions to apply changes. Conflicting packages discovered at startup are skipped, with errors identifying their claims.

Rows share one loading decision per page and component name. Loading has a five-second deadline; a timed-out implementation cannot replace the native view later on that page. Import and render failures restore the native view. Core state remains above the presentation boundary, while extension-local state can be lost on failure. An uncontained suspension commits that mount to its native view; use local Suspense for extension-owned asynchronous content. Event and asynchronous callback failures require useExtensionAction and remain separate from render boundaries.

See Component Replacements for registration and testing examples.

Hooks

Server Data

These factories return query options for the Panel's own transport and cache. Use the server UUID for files, startup, and backups to share the native page's cache entries.

invalidateServerData(uuid, domains) returns a promise for native cache invalidation. Domains are server, files, fileContent, startup, and backups. File and backup invalidation covers all cached directories or pages for that server. Await it when your own mutation changes native data.

Mutations

Each hook returns isPending, error, data, mutateAsync(input), and reset(). Await mutateAsync from a guarded action handler. These hooks use the native cache updates and invalidation; startup writes are serialized per server.

The hooks do not replace backend authorization. Check the user's permission before showing a write control.

Navigation

A core destination is { to, params?, search?, hash?, replace? }. The to value must be a supported core route, and required route parameters are checked by TypeScript. An extension destination is { extension, screen, params?, search?, hash?, replace? }; pass the declared screen ID and the parameters needed for its screen and resource parent.

Table Columns

columns.register(name, { id, label, component }) supports these tables:

The component receives { data }, typed as ExtensionTableRows[Name]. Column IDs use lowercase letters, numbers, and hyphens, starting with a letter, up to 48 characters. Columns follow extension order and render after core columns. Each cell has an error boundary.

Components

The SDK also exports toast, for notifications.

HTTP

Types

Build Configuration

Build your extension with defineExtensionConfig from @pterodactyl/sdk/vite:

import { defineExtensionConfig } from '@pterodactyl/sdk/vite';

export default defineExtensionConfig({ entry: 'src/client/index.tsx' });

It accepts entry (required), outDir (default dist), and plugins.

Testing and Styling

Test host options are extensionId, path, user, siteSettings, server, and a typed admin resource. The returned host has Wrapper, queryClient, navigate(destination), emitWebsocket(event, data), setConnected(connected), and dispose(). Create one host per test environment at a time; unmount its wrapper before disposing it.

createTestServer accepts identifier, uuid, name, owner, permissions, and status. Source checkouts build the test runtime with npm run sdk:testing at the Panel root.

createComponentTestHost accepts a supported component name and { model, extensionId? }, and returns Wrapper and typed replacement props. Its defaults and parts are the Panel's native implementations. The model fixture helpers accept partial model overrides.

Frontend scaffolds include tests, CI, PostCSS, a stylesheet, and OpenAPI generation. Their npm run api:generate expects an extension openapi.yaml. Generate it from the Panel root with composer docs:openapi and npm run extension:api:generate -- {id} after loading the extension's routes.

Entry CSS loads before setup; imported screen styles load with their screen chunk. Custom selectors should be scoped to the extension. See Components and Styling.

Slots

Slots are named places on the Panel's pages where extensions may render components. Register them with slots.register(name, component). The data column shows the component's data prop.

Slot Data

The native user form fields are email, username, nameFirst, nameLast, password, rootAdmin, and language. Contributed controls share validation, pending state, submission, and persistence with the Panel's form. Extension-specific values need scoped settings or an extension endpoint.

Navigation Slots

Authentication Slots

Dashboard Slots

Account Slots

Server Slots

Admin Slots