Extension Reference

Introduction

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

Manifest

extension.json supports these keys:

Each entry in ui.screens supports these keys:

A screen whose when conditions fail has no navigation item, and its URL shows the not-found page. when must declare an egg rule or "runtime": true.

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

Extension Icons

The icon key accepts two forms:

"icon": "life-buoy"

"icon": "resources/icon.png"

A value made of lowercase letters, numbers, and single hyphens is a Lucide icon name. A name this Panel does not ship renders the default icon, and p:extension:doctor warns about it.

A value ending in .png, .jpg, .jpeg, or .webp is an image path, relative to the extension's root and using / between directories. No directory or file name may start with a dot, so the path cannot leave the extension. The Panel accepts the image when:

• It is a PNG, JPEG, or WebP image, judged from the file's contents rather than its name. SVG is not supported.
• It is at most 512 KB and at most 2048 pixels on each side.
• It resolves to a file inside the extension. A symlink that points outside the extension is refused.

Use a square image of at least 128 pixels. The Panel shows it at 40 pixels, scaled to fit, on the extension's own background.

The Panel serves the image from the installed extension to administrators who can view extensions, at /api/admin/extensions/{id}/icon, so it shows while the extension is disabled. It does not need to be in dist. The icon_url field of the Admin API's extension list holds the image's URL, including a version that changes with the file's contents. An image that is missing or fails these checks leaves icon_url empty, and the page shows the extension's initials. The manifest stays valid, and p:extension:doctor warns about the image.

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

Pterodactyl\Extensions\ExtensionProvider has these protected methods:

Route Helpers

Each helper loads a route file under a prefix, with the Panel's middleware. registerApiRoutes calls the first four.

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

Settings

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

The admin form validates submitted values against their definitions. Updates can be partial. 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:

The global scope, each model's scope, and each model's form field values are separate. Deleting a model deletes its scoped settings and field values. ExtensionSettings::preload($stores) loads several stores together. An ExtensionSettingsDefinition also supports forUser and forServer.

Permissions

Register 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 can also use these core permissions:

Form Fields

registerFields($model, $fields) adds the fields declared by a class extending Pterodactyl\Extensions\Fields to the admin create and edit forms of a model. Register one class for each model. Every method of the class is optional, and each is called through the service container, so it may type-hint the model and any other dependency.

Methods other than values and save also run while a model is created, so their model parameter must be nullable. Implement both values and save, or neither: without them, the Panel stores the values, readable with settings()->fields($model). Registering an unsupported model, a class that does not extend Fields, only one of values and save, or the same model twice stops the extension from loading.

GET /api/admin/extensions/forms lists, for each admin form, the enabled extensions that add fields to it and that the signed-in administrator may change.

Events

The Panel dispatches these events from the Pterodactyl\Events\Extensions namespace. Each has a public $manifest property unless 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. Browsers do not cache responses.

Workers and web requests must share a cache store. extensions.progress_retention_seconds sets retention, defaulting to 3,600 seconds after the last update. Store durable results or audit records elsewhere.

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 below.

Use definePterodactylExtension({ setup }) for an entry definition, or defineConfiguredExtension(parseConfig, { setup }) with generated configuration and screen types. setup is synchronous; its registrations take effect together once it succeeds.

Setup Context

setup 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.

server.files.editor replaces the editing surface of the file editor. FileEditorModel has path, name, isNew, content, language, readOnly, dirty, and saving, plus change(content), save(), and saveAs(name). For a new file, path is its directory and name is empty. language is a MIME type such as text/x-yaml. Call change after every edit; the Panel saves that text. save and saveAs resolve whether the file was saved.

server.files.manager replaces the file browser's toolbar, listing, and selection bar. FileManagerModel has directory, entries, truncated, loading, refreshing, selection, permissions, and actions. Each FileManagerEntry has name, path, kind, size, mimetype, mode, modeBits, modifiedAt, and openable, with at most 250 entries per directory. permissions has boolean create, update, delete, and archive. actions has open, navigate, newFile, select, refresh, createDirectory, rename, remove, copy, archive, extract, chmod, download, and upload, which run the Panel's own mutations. remove does not ask for confirmation. The file manager slots and the server.files.details replacement render only inside the native parts you keep.

The server card and file details are non-interactive content inside core links. The Panel keeps 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 instead of registering React.lazy.

A component has one enabled owner. Conflicting enable and update requests fail before activation. Enabling or disabling the extension toggles its replacements; reload open browser sessions to apply the change. Conflicting packages found at startup are skipped, with errors naming 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 stays above the presentation boundary; 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 need useExtensionAction, separate from render boundaries.

See Component Replacements for registration and testing examples.

Hooks

Server Data

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

invalidateServerData(uuid, domains) invalidates the native cache and returns a promise. 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. The hooks apply 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? }. to must be a supported core route; TypeScript checks required route parameters. 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' });

Options: entry (required), outDir (default dist), and plugins.

Testing and Styling

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

createTestServer accepts identifier, uuid, name, owner, permissions, and status. In a source checkout, build the test runtime with npm run sdk:testing from the Panel root.

createComponentTestHost accepts a supported component name and { model, extensionId?, prefix? }, and returns Wrapper, typed replacement props, and dispose(). Call dispose() after unmounting the wrapper. 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. To generate it, load the extension's routes, then run composer docs:openapi and npm run extension:api:generate -- {id} from the Panel root.

Entry CSS loads before setup; imported screen styles load with their screen chunk. Scope custom selectors to the extension. See Components and Styling.

Slots

Slots are named places on Panel pages where extensions render components. Register a component 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. To add fields of your own, use Form Fields and forms.extend instead.

Navigation Slots

Authentication Slots

Dashboard Slots

Account Slots

Server Slots

Admin Slots