Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calagopus/panel/llms.txt

Use this file to discover all available pages before exploring further.

The Calagopus extension system lets you expand the panel beyond its built-in capabilities without modifying core code. Extensions come in two forms: backend extensions, which run server-side and can add routes, background tasks, database migrations, permissions, and auth providers; and frontend extensions, which run in the browser and can add pages, UI components, custom themes, and new routes to the panel.

​
Extension types

Auth providers

Replace or supplement the built-in username/password login with a custom authentication backend.

Frontend extensions

Add pages, modify UI components, inject custom themes, and register new routes in the panel interface.
Every Calagopus extension is a single .c7s.zip archive that bundles a compiled Rust crate (backend), a TypeScript module (frontend), and optional database migrations. The archive is validated on upload and rejected if any required file is missing or malformed.

​
Requirements

Extension management is only available in the heavy Docker image (ghcr.io/calagopus/panel:heavy). The standard image does not include the build toolchain. If you try to upload or remove an extension while running the standard image, the API returns 501 Not Implemented.
You must use ghcr.io/calagopus/panel:heavy to install or remove extensions. The extension management endpoints are not available on the standard image.
The heavy image mounts an /app/extensions directory where uploaded archives are stored. Map this directory to a persistent volume in your compose.yml so extensions survive container restarts.
compose.yml
volumes:
  - ./build/extensions:/app/extensions
  - ./build/extension-migrations:/app/repo/database/extension-migrations

​
How extensions are loaded

When the panel starts, it reads every .c7s.zip file from /app/extensions, validates the archive, extracts the backend and frontend code, and compiles the backend Rust crate into the running binary. This process happens at container build time — not at runtime — which means the container image is rebuilt each time you add or remove an extension. The build process is asynchronous. After uploading a new extension you must trigger a rebuild from Admin → Extensions → Rebuild before the extension takes effect.
After uploading or removing an extension, the panel needs a rebuild. Monitor progress in the build log viewer at Admin → Extensions.

​
Managing extensions

Navigate to Admin → Extensions to see all installed extensions. The panel shows each extension’s package name, version, description, and authors.

​
Installing an extension

1

Obtain the extension archive

Download or obtain the .c7s.zip extension archive from the extension author.
2

Check panel version compatibility

The archive’s Metadata.toml declares a panel_version semver requirement. The panel rejects archives that do not match the running panel version.
3

Upload the archive

In Admin → Extensions, click Upload extension and select the .c7s.zip file. The panel validates the archive and registers it as a pending extension.
4

Trigger a rebuild

Click Rebuild to start the container rebuild process. Watch the build log to confirm the extension compiled successfully.

​
Removing an extension

1

Open extension details

In Admin → Extensions, locate the extension you want to remove.
2

Choose migration behavior

You can opt to roll back the extension’s database migrations before removal. Enable Remove migrations if you want the database changes undone; leave it disabled if you want to keep the data.
3

Delete and rebuild

Confirm deletion. The archive is removed from /app/extensions. Trigger a rebuild to apply the change.

​
Checking rebuild status

The panel exposes a status endpoint that reports whether a rebuild is in progress and which extensions are pending. You can also view the raw build log from Admin → Extensions → Build log.
Only one rebuild can run at a time. If a rebuild is already in progress, subsequent rebuild requests return a 409 Conflict error until the current build finishes.

​
Extension package naming

Extension package names follow a three-segment reverse-domain scheme: tld.author.identifier. For example, com.acme.my-auth. The segments have these constraints:
SegmentCharactersLength
TLDLowercase ASCII letters only2–6 characters
AuthorLowercase ASCII letters, digits, hyphens3–30 characters
IdentifierLowercase ASCII letters, digits, hyphens4–30 characters
Internally the panel converts the package name to an identifier by replacing . with _ (e.g., com.acme.my-auth → com_acme_my-auth).

​
Security considerations

Extensions run with full access to the panel’s database, settings, encryption keys, and inter-process state. Treat extensions with the same level of trust as the panel itself.
Only install extensions from authors you trust. A malicious extension has full access to all panel data and can execute arbitrary code in the container.
The admin permission extensions.manage is required to upload, remove, or rebuild extensions. Grant this permission only to administrators who are responsible for infrastructure maintenance.

​
Next steps

Auth providers

Learn how to install and configure a backend auth provider extension.

Frontend extensions

Understand the frontend extension API and how to add pages, components, and themes.

Build docs developers (and LLMs) love

Get started for freeTalk to us