Extensions

Extensions are the primary way to extend the functionality of the Panel. They allow you to add backend logic, frontend interfaces, database migrations, and deep system integrations in a structured and controlled way.

For a high-level architectural breakdown of how extensions work within the system, see the Technical Overview section.

Getting Started

If you are new to extensions, start here:

• Installing Extensions - Install .c7s.zip extensions in the Panel
• Uninstalling Extensions - How to remove extensions and what happens to their data
• Disabling Extensions - Turn an extension off without uninstalling or recompiling it
• Switching to the Heavy Image - Use the :heavy Docker image variant to enable extension support in a containerized setup
• Patching and Adding Translations - Override the Panel's built-in translations or add a new language on the heavy image
• Development Environment - Set up a local environment for building extensions
• Extension File Structure - How extensions are structured across frontend, backend, and database layers

Concepts

Extensions are built around several core systems:

• Theming - Customize the look and feel of the Panel interface
• Events - React to system and user actions
• Settings - Define configurable extension options
• Routing - Add custom backend routes
• Permissions - Control access to extension features
• CLI Commands - Extend the Panel command line interface
• Background Tasks and Shutdown Handlers - Run async or lifecycle-based logic
• Update Checks and Extension Calls - Communicate between extensions and system services
• Frontend API Calls - Interact with backend APIs from the UI
• Activity Logging - Record extension-related actions
• Translations - Provide multi-language support
• Mounting UI - Inject UI elements into the Panel interface
• Quick Actions - Add entries, categories and prefix modes to the command palette
• File Manager - Slot components, context menu items, file icons and custom editors into the file manager
• Toasts - Show transient feedback to the user
• Frontend Events - Change or cancel toasts, websocket frames, API requests, clipboard use and more before the Panel acts on them
• Extending Models - Add fields to existing data models
• Email Templates - Define custom email templates for notifications and communications
• Speaking Game Protocols - Open raw TCP/UDP tunnels to a server's port to query it directly
• File Storage - Store extension-owned files on the local disk or an S3 bucket
• Forms - Add fields to the Panel's existing forms
• User Settings - Store per-user preferences that sync across devices

Installation Methods

Extensions can be installed in multiple ways depending on your setup:

• Docker-based installation (requires :heavy or :nightly-heavy image)
• Development environment installation
• Manual .c7s.zip placement into the extensions directory

See Installing Extensions for full instructions.

Structure Overview

Extensions follow a standardized multi-part structure consisting of:

• Frontend (React-based UI layer)
• Backend (Rust-based logic layer)
• Database migrations (optional)

This structure defines how extensions are loaded, initialized, and integrated into the Panel.

For a complete breakdown of directories, required files, package naming, and extension entrypoints, see Extension File Structure.