Repository navigation
FTP Connection
Devices / FTP Connection
Think of an FTP Connection as your saved connection to one server. It keeps the address and login details in Homey, so you can browse files or use that server in a Flow without entering them each time.
On this page
- Pairing
- Device settings
- URL modes
- File browser
- Choosing transfer settings
- Connection security
- Next steps
Pairing means adding the connection as a device in Homey. If this is your first connection, follow the steps in Getting started.
FTP Client may list FTP servers discovered on the local network. It also checks for supported local services, including Micro Web Server and HTTP/FTP Server. Select the matching server to pair it.
If your server is not discovered, add a custom FTP Connection and enter the server's hostname or IP address and port in the device settings. Configure the username, password, and security settings there as well.
Open the device settings for your FTP Connection in Homey to change these options. Save your changes, then reopen Repair to check the connection.
| Setting | Purpose |
|---|---|
| IP or hostname | The server's numeric network address or network name. Enter the address only, without a folder or ftp://. |
| Port | The connection number used by the FTP server; the default is 21. |
| Username | Account used to log in. |
| Password | Password for the account. |
| Secure | Connect using FTPS. Enable this if the server requires encrypted FTP. |
| Allow incorrect certificate | Permit a certificate that cannot be validated when using FTPS. This reduces connection security; enable it only for a server you trust. |
| Work (Default) Directory | This setting is currently present in the device settings but is not applied by the app. The FTP account's server-side starting directory determines what the browser shows. |
| Download Time (Seconds) | How long FTP Client keeps temporary data for repair-view file downloads and image tokens made from FTP files. The default is 60 seconds. |
| URLs used for icons and images | Select how the file browser obtains its icons: local HTTP, the Homey local HTTPS address, or the Homey cloud HTTPS address. |
| URLs used for downloading files | Select the URL mode used for file downloads from the repair view. |
| URLs used for file URLs | Select the URL mode used by FTP-file image token generation. |
These options choose how your browser, device, or app reaches files through Homey. HTTP uses an unencrypted connection; HTTPS uses an encrypted one. The settings label calls the encrypted options SSL.
- Local: HTTP through Homey's local address. Choose it for a client that can reach Homey on the local network. HTTP does not encrypt the transfer.
- Local (SSL): HTTPS through Homey's local hostname. Choose it for local access when HTTPS is needed; the device opening the link must be able to find and connect to Homey using that network name.
- Cloud (SSL): HTTPS through Homey's cloud connection. Choose it for remote access when a local address cannot be reached. It depends on the cloud connection being available.
The three URL settings are independent. For example, you can load picker icons locally while downloading files from the repair view using Cloud (SSL). They do not select the output of Get file URL, which returns separate URL and Cloud URL tokens.
When using the repair view away from home, choose Cloud (SSL) for file downloads. If icons also fail to load remotely, use Cloud (SSL) for icons too. Local HTTPS still requires access to your home network.
For this device's five action cards, see FTP Connection Flowcards. Each card has a dedicated page under the device's Actions index.
The browser is available from the device's Repair view in Homey. It can:
- List folders and files, and switch between grid and list views.
- Create folders and rename, move, and delete files or folders.
- Upload multiple files to the selected folder.
- Download a file by opening it or using its download control.
Right-click an item to open its context menu on desktop. On touch devices, use the item's controls or press and hold where the Homey interface supports it. Folder deletion may delete its contents as well.
See Getting started for screenshots and upload controls.
- How long files remain available: choose Download Time (Seconds) long enough for a repair-view download or the next image action to finish. Create the download or image just before you need it. The separate Get file URL card uses BLL's URL helper, not this lifetime setting.
- Size and frequency: Homey holds downloaded file data in memory. Test with small files before large exports or frequent image loops; more or larger simultaneous work needs more memory and transfer time. Browser uploads and base64 Flow tokens are handled differently, so a successful browser upload does not tell you how large a Flow upload can be.
- Storage: fixed filenames replace files, while varying filenames grow an archive. For scheduled exports or camera snapshots, choose a retention policy on the server: decide how long to keep old files and when to delete them, so the archive does not fill your storage.
These choices are independent of FTP account permissions. First verify a small upload and download, then change one setting at a time and repeat the relevant test.
A server certificate helps Homey check the server's identity when using FTPS. If that check fails, first check the address and certificate rather than turning the check off.
Warning
Allow incorrect certificate disables certificate validation. Prefer a valid certificate and matching hostname; use this exception only for a server you trust.
Use the server's configured FTP or FTPS mode. If an FTPS connection fails, check that Secure matches the server configuration. If the server uses a self-signed or otherwise untrusted certificate, Allow incorrect certificate may be required.
The FTP server must be reachable from Homey. Choosing a local or cloud URL mode controls how clients reach files served through Homey; it does not change how Homey connects to the FTP server.
FTP Client uses FTP or FTPS, not SFTP over SSH. Plain FTP sends credentials and data without encryption; prefer FTPS, especially for internet-hosted servers. Use a hostname matching the server's certificate and a valid certificate where possible, rather than disabling certificate validation.
Once the connection passes the small-file transfer check, choose a card from FTP Connection Flowcards. For a failed connection, use the ordered troubleshooting checks.
Support development - If FTP Client is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!