Installation

Version 1.1.0 · Krapple Studios · for Pterodactyl Panel 2.0

This guide is for panel administrators. For what each feature does, see the overview; for common problems, Troubleshooting.

Before you start

1. Take a backup of the panel database and storage/app.
2. Note your panel version — Admin → Panel, or php artisan p:info from the panel directory.
3. Make sure PHP meets the requirements below.

Requirements

Panel	Pterodactyl 2.0, v2.0.0-beta.2 or later (including source checkouts)
SDK	2.0.0-beta.6 or later
PHP	8.3+
PHP extensions	GD for thumbnails (WebP when available); ZipArchive for archive previews; pdo_sqlite for the database viewer
Panel services	The scheduler and queue worker must run

The extension degrades gracefully: without GD, thumbnails turn off and previews still work; without pdo_sqlite, the database viewer is unavailable.

Install the extension

Through the panel

1. Sign in as an administrator.
2. Go to Admin → Extensions → Upload.
3. Choose file-manager-pro-1.1.0.pteroext and upload it.
4. Press Enable.
5. If you want the companion editor, repeat with file-manager-pro-editor-1.1.0.pteroext.

From the command line

Run these in the panel directory:

php artisan p:extension:install file-manager-pro-1.1.0.pteroext --enable
php artisan p:extension:install file-manager-pro-editor-1.1.0.pteroext --enable   # optional
php artisan optimize:clear

Enabling sets up the extension's own storage and builds its frontend. It does not modify the panel's core files.

Upgrading from 1.0.0

Add --replace to both commands (or use Replace in the panel):

php artisan p:extension:install file-manager-pro-1.1.0.pteroext --enable --replace
php artisan p:extension:install file-manager-pro-editor-1.1.0.pteroext --enable --replace
php artisan optimize:clear

Your settings, file history, Recycle Bin and stored versions are kept. Users may need one hard refresh (Ctrl+Shift+R) after the upgrade, because the frontend bundle changed.

First-run checks

The scheduler and queue worker

Open Admin → Overview. File Manager Pro adds a notice when the scheduler or queue worker has not run recently. For reference, the usual cron entry is:

* * * * * cd /path/to/pterodactyl && php artisan schedule:run >> /dev/null 2>&1

and a worker is normally run under your process manager:

php artisan queue:work --tries=3 --timeout=900

Settings

Open Admin → Extensions → File Manager Pro and review:

Tab	Setting	Default	Notes
Recycle Bin	Recycle Bin	on	Off makes deletes permanent, as before
Recycle Bin	Keep items for (days)	7	1–90; individual servers can override
Recycle Bin	Bin size cap (GB / % of disk)	2 GB / 10 %	The smaller limit applies
Recycle Bin	Send every panel delete to the bin	on	Also catches API and other-extension deletes
File history	File history	on
File history	Versioned file types	a curated list	Space-separated extensions
File history	Max versioned file size	2 MB
File history	History storage per server	100 MB
File history	Storage disk	local	s3 uses the S3 fields
Previews	Thumbnails / SVG / Archive listing	on / off / on	SVG needs a current Imagick
Previews	Max image / archive / media size	15 / 100 / 200 MB
Previews	Database viewer	on	SQLite, read-only
Previews	Max database size to open	100 MB
Downloads	Temporary archive lifetime	15 min	Used by "Download as zip"

Permissions

Every feature needs a core file permission and, for the Recycle Bin and history, an extension permission as well. Grant them in Admin → Users → Edit → Permissions, or per server under Subusers.

Feature	Core permission	Extension permission
Browse, grid, list	file.read	—
Thumbnails, Quick Look, download	file.read-content	—
Create, upload, paste	file.create	—
Rename, move, permissions, edit	file.update	—
Delete (to the bin)	file.delete	—
See the Recycle Bin	file.read	ext.file-manager-pro.bin-read
Restore from the bin	file.create	ext.file-manager-pro.bin-restore
Delete permanently, empty the bin	file.delete	ext.file-manager-pro.bin-purge
See history	file.read-content	ext.file-manager-pro.versions-read
Restore a version	file.update	ext.file-manager-pro.versions-restore
Pin or label versions, save one by hand, change tracking	file.update	ext.file-manager-pro.versions-manage
Compress, extract, download as zip	file.archive	—

Controls a user cannot use are disabled, with a tooltip naming the missing permission. The server enforces the same rules, so a disabled button cannot be bypassed.

Verify the install

1. Open a server → Files. You should see the new file manager with grid and list views.
2. Delete a small test file. It should move to the Recycle Bin, with an Undo option.
3. Edit a config file such as server.properties, save it, then open History. A "Before editing" and a "Saved in editor" version should be listed.
4. Press Space on an image to open Quick Look.

If a step fails, see Troubleshooting.

Uninstall

php artisan p:extension:disable file-manager-pro
php artisan p:extension:uninstall file-manager-pro

Uninstalling keeps the extension's history and stored versions, so a reinstall resumes where it left off. To reclaim the space, delete the extension's storage folder yourself. Files in a server's Recycle Bin stay there until you remove them, and they are excluded from backups. Remove the companion editor first if you use it, because it needs File Manager Pro.

After a panel upgrade

Check the extension reports itself healthy, then clear the panel cache:

php artisan p:extension:doctor .    # from the extension directory
php artisan optimize:clear

The doctor checks compatibility, autoload paths and the built frontend, and tells you what to do if something moved.