SFTP Setup and Secure Access

Published · Last updated: May 2026 · 3 min read

Who this is for

Users who want to transfer large numbers of files to/from a site using an SFTP client (such as FileZilla, Cyberduck, or WinSCP) rather than the in-browser File Manager.

Prerequisites

Site is running with SSH connectivity.
The server's firewall allows inbound connections on port 22.
You have an SFTP client installed on your computer.

What SFTP Access Provides

SFTP (SSH File Transfer Protocol) gives you a dedicated set of credentials to connect directly to the site's document root. Unlike the in-browser File Manager, SFTP is suitable for:

Bulk uploads (plugins, themes, media files)
Transfers from automation pipelines
Large file uploads where a browser connection might time out

How to Set Up SFTP for a Site

Open the site detail.
Go to the SFTP tab.
Click Set Up SFTP Access (requires Owner or Admin role).
Confirm.

CloudAIPilot creates a dedicated SFTP user on the server scoped to the site's document root. The setup runs as a background job via BullMQ.

Once complete, the SFTP credentials are shown once:

Host: the server's IP address or hostname
Port: 22
Username: the auto-generated SFTP username
Password: the auto-generated password (shown once — copy it now)
Document root: the directory you will land in

⚠️ Save the password immediately. It is shown in plain text only during initial setup. If you lose it, use "Reset SFTP Password" to generate a new one.

How to Connect with an SFTP Client

FileZilla example:

Open FileZilla.
Go to File → Site Manager → New Site.
Set:

Protocol: SFTP – SSH File Transfer Protocol
Host:
Port: 22
Logon type: Normal
User:
Password:

Click Connect.

You will land directly in the site's document root.

How to Test SFTP Connectivity

In the SFTP tab, click Test Connection.
CloudAIPilot attempts to connect to the SFTP user and reports success or failure.

How to Reset the SFTP Password

If you forgot the password or suspect it was compromised:

Open the site detail → SFTP tab.
Click Reset SFTP Password.
Confirm.
A new password is generated and shown once. Copy it immediately.

Security Notes

The SFTP user is chrooted to the site's document root — they cannot browse outside the site's directory.
The SFTP password is stored encrypted in CloudAIPilot. It is decrypted only when displayed on request.
Use strong, unique passwords. If sharing credentials with a client or contractor, reset the password when they no longer need access.

What Success Looks Like

SFTP test shows a connection success. Your SFTP client connects and shows the site's document root directory. File uploads complete successfully.

Common Issues and Fixes

Issue	Likely cause	Fix
"ALREADY_CONFIGURED" error	SFTP was already set up	No action needed — click "View Credentials" or use "Reset" to get a new password.
"NO_DOCROOT" error	Site has no document root set	Ensure the site provisioning completed successfully.
Connection refused on port 22	Server firewall blocking port 22	Open port 22 in the firewall — see KB-02-11: Firewall Basics.
"Authentication failed"	Wrong password	Use the SFTP Reset to generate a new credential.