Install inside FreeScout.
Open Manage → Modules, enter the license key when required, install the module, and activate it. Official module code is downloaded by the FreeScout instance.
View official modules ↗Custom module installation
Install carefully. Keep a way back.
This guide covers community and custom FreeScout modules. It is intentionally conservative: confirm compatibility, create a backup, upload the correct folder, activate one change at a time, and verify the result before moving on.
Know which path you are using
Official and custom modules install differently.
The module’s own README and release notes always take priority over this general guide.
Upload into the application’s Modules folder.
Use the developer’s release package, extract one complete module directory into /Modules, then activate it from Manage → Modules.
Hosting and file access
Choose the level of control you actually need.
A managed host reduces server work. Manual community-module installation still requires a supported way to access the FreeScout files.
PikaPods
PikaPods lists FreeScout as a hosted app and is a practical starting point when you want to launch FreeScout without building a server setup from scratch.
Before committing: confirm the current file-access method available for the FreeScout pod if community-module uploads are essential to your plan. Managed platforms may not expose the same SFTP or shell access as a traditional VPS.
View FreeScout on PikaPods ↗SFTP or SSH file access
Choose a host that gives you secure file access to the FreeScout application. SFTP runs over SSH and is preferred over unencrypted FTP.
- Host name or server IP
- SFTP port, commonly 22
- Username plus password or SSH key
- Access to the FreeScout root directory
On Windows, WinSCP is a practical SFTP client. FileZilla is another common option. Use credentials supplied by your host.
Backup-first procedure
A reliable custom-module installation.
Install one module at a time. That makes any failure easier to isolate and reverse.
- 01
Read the release notes and compatibility information.
Confirm the supported FreeScout version, PHP version, database notes, required official modules, and any upgrade-specific steps. Do not assume the repository’s default branch is an installable release.
- 02
Create a complete backup.
Back up the database and the FreeScout application files. Confirm that you know how to restore them. A backup that has never been located or tested is not a rollback plan.
- 03
Download the intended release package.
Prefer the developer’s published release ZIP when one is available. Avoid GitHub’s automatic “Source code” archive unless the module documentation explicitly tells you to use it.
- 04
Inspect the extracted folder before uploading.
The module folder should directly contain its module files. Avoid accidental nesting such as
/Modules/repository-main/ModuleName. The final path should resemble/Modules/ModuleName. - 05
Upload the module folder into
/Modules.Use SFTP, SSH, your host’s file manager, or the supported access method provided by the platform. Do not upload the module into
/public/modules; FreeScout manages the public symlinks during activation. - 06
Check ownership and permissions.
The web-server user must be able to read the module and create required files or symlinks. Do not solve permission errors by making everything world-writable or using blanket
777permissions. - 07
Activate the module.
Sign in as an administrator, open Manage → Modules, locate the custom module, and activate it. Run database migrations only when the module instructions or FreeScout’s status tools indicate they are required.
- 08
Verify the interface, logs, and core workflow.
Check the module page, browser console, Manage → System → Logs, ticket viewing, replies, scheduled jobs, and mobile layout where relevant. Confirm permissions with both an administrator and a normal user.
After activation
Do not stop at “it appears in the menu.”
- Open and use the main feature
- Check application logs
- Test an affected ticket workflow
- Check mobile layout
- Confirm mailbox permissions
- Run scheduled tasks if relevant
- Confirm no console errors
- Record the installed version
Rollback
When activation causes a problem.
Start with the least destructive action. Keep the backup untouched until normal operation is confirmed.
FreeScout module troubleshooting ↗- 1
Deactivate the module from Manage → Modules when the interface is still available.
- 2
Review Manage → System → Logs and the browser console before changing more files.
- 3
Remove or rename only the affected module folder if FreeScout no longer loads.
- 4
Restore the database or files from backup when the module changed data and a clean reversal is required.
Installation help
Need a module reviewed or installed safely?
Send the FreeScout version, host, module link, database type, and the issue you are trying to solve. Custom support is scoped before any changes are made.