SSH Gateway

SSH, also known as Secure Shell, is the method of connecting from your computer to the web server where your site is hosted. With SSH access you can use a variety of command-line tools such as: WP CLI, MySQL command line, bash, and Composer to manage your website. WP Engine’s SSH Gateway will connect to a container, like a sidecar, that sits alongside the website. This allows authorized users to access the website’s filesystem and database.

SSH Gateway uses key-based authentication for even greater security than a simple username and password combination, and is only accessible to users who have been granted permission to access the specific environment.

SSH stands for “Secure Shell” and is the authentication method two devices (computers, servers, or other internet devices) use to communicate with each other. On the WP Engine platform, SSH Gateway access means the ability for you to connect remotely from your local machine to a container where your site’s content is hosted. Developers who are testing, building, or managing multiple websites can and should use SSH Gateway. SSH Gateway should be used by people who are familiar with the use of command line, bash, and WP CLI.

SSH Gateway is ideal because it allows users an easy, secure interface to interact with their site’s files and content. This includes using WP-CLI to manage WordPress^® settings and administration, navigating files and directories, using rsync and SCP to move and transfer files, and using MySQL command line to manage databases.¹ Users can even create scripts and bash loops to automate tasks that previously would take a lot of manual work. WP CLI allows developers and site administrators to manage their site outside of the confines of the WordPress back-end, which allows for faster work and chained commands to automate site workflows.

WP Engine uses an SSH “sidecar” that sits alongside your server with a timeout of 10 minutes. Each site will have its own unique connection details and a separate sandbox to ensure there is no cross-contamination of sites or resources. This ensures the highest security level while allowing access to your site, without requiring additional steps such as IP allowing. When connected through SSH Gateway, you will be able to access the WordPress files and database as though you were connected directly to the server, but you won’t see all of the standard processes that are running on a server, such as PHP or MySQL.

The SSH session does not use the Memory dedicated to the server itself and as such will also not cause load to increase. SSH Gateway processes are not affected by the PHP timeout. The PHP kill script exists on the server itself, while the commands are running in the sidecar container.

SSH multiplexing is supported, which provides a way to reuse a connection for multiple SSH sessions to reduce the connection overhead for subsequent sessions. Since SSH Gateway spins up a new sidecar environment for each connection, multiplexed sessions reuse the same environment resulting in much faster connection times.

If desired, add the content below config to ~/.ssh/config to enable multiplexing for a given WP Engine environment.

Host *
ControlPath ~/.ssh/socket-%C
ControlMaster auto
ControlPersist 10m

SSH Gateway allows for file and database access through a secure interface, as well as access to tools like WP-CLI and MySQL command line.

To connect to the SSH Gateway, there are multiple steps outlined in sections below.

1. Create an SSH key on your computer.
2. Create a config file on your computer.
3. Add your SSH key to the WP Engine User Portal.
4. Run the SSH connection command.

If you already have a key that you want to use for shell access, then you can skip to the config file step and specify the key in your config file. You can view the section below about viewing and validating existing keys.

Otherwise you’ll need a new key pair which you can generate with these simple instructions:

1. Open a Terminal or Command Prompt window from your computer.
2. Use ssh-keygen to generate a new key as shown below:
   • Mac: ssh-keygen -t ed25519 -f ~/.ssh/wpengine_ed25519
   • Windows: ssh-keygen -t ed25519 -f C:\Users\YourUsername\.ssh\wpengine_ed25519
     Note: Be sure the replace “YourUsername” with the username for your computer.
     • If the .ssh folder doesn’t exist yet then you can add the directory from within your “YourUsername” directory, with the mkdir command.
       cd C:\Users\YourUsername
mkdir .ssh
3. Hit enter or return to leave the passphrase blank.
   • If you wish to set a password, you may. However the security benefit is debatable and it cannot be recovered if lost.
4. Once the process has completed, run the following to print the contents of the public key file:
   • Mac: cat ~/.ssh/wpengine_ed25519.pub
   • Windows: type C:\Users\YourUsername\.ssh\wpengine_ed25519.pub

If you choose to use the PuTTY program on Windows, you must also install the PuTTYgen utility.

1. When you install the PuTTY program, also install the PuTTYgen utility
2. Open the PuTTYgen utility to generate your SSH key
3. When asked which type of key to generate, select ED25519
4. Click the Generate button to create your public and private key pair
5. Save both the public key and the private key locally and take note of where the files will reside on your computer

When asked to enter the public key into the WP Engine User Portal we recommend simply copying the key from the top of the window in PuTTY.

After generating an SSH key pair, it is best practice to setup an SSH configuration file.

The SSH config file tells your computer which public/private key pair should be used for which hostname. It can prevent many issues and we highly recommend setting one up now to prevent issues down the road.

The configuration file will simply be named config and will live in the .ssh folder within your User directory.

• Mac: ~/.ssh/config
• Windows: C:\Users\YourUsername\.ssh\config

1. Open the Terminal app.
2. Type the following command: cd ~/.ssh
3. Type the following command: vim config
4. Inside the file, type i to insert text.
5. Paste the following contents:
   • Host *.ssh.wpengine.net
IdentityFile ~/.ssh/wpengine_ed25519
IdentitiesOnly yes
6. Hit the ESC button, and then type :wq to save the file and exit the vim editor.

1. Open the Command Prompt app.
2. Type the following command: cd C:\Users\YourUsername\.ssh
   Note: Replace “YourUsername” with the username for your computer.
3. If the config file does not already exist in the .ssh folder, then type the following command to create the file: type nul >> config
4. Type the following command to edit the file in the Notepad app: notepad config
5. Paste the following contents into the file within the Notepad app:
   • Host *.ssh.wpengine.net
IdentityFile C:\Users\YourUsername\.ssh\wpengine_ed25519
IdentitiesOnly yes
   • Note: In the above text, replace “YourUsername” with the username for your computer.
6. Select File > Save within the Notepad app.

If you are a developer with several SSH keys and prefer to specify a key for each environment, the following SSH Config can be used instead:

Host MYCOOLALIAS
User ENVIRONMENTNAME
Hostname ENVIRONMENTNAME.ssh.wpengine.net
PreferredAuthentications publickey
IdentityFile ~/.ssh/YOURKEYFILENAME_ed25519
IdentitiesOnly yes

Be sure to update the following accordingly:

Update MYCOOLALIAS to the alias name you wish to use.
Update ENVIRONMENTNAME to the unique WP Engine name of the environment. This is also the name of the User.
Update ~/.ssh/YOURKEYFILENAME_ed25519 to your private key file path. This should typically be in the ~/.ssh/ directory and end in _ed25519.

To connect, you would then simply type the alias nickname you’ve assigned. For example: ssh MYCOOLALIAS

Specifically, use this if you chose not to create the SSH configuration file previously. Replace “ENVIRONMENT” with the name of the environment that you are connecting to. For the Windows command replace “YourUsername” with the username for your computer.

Mac: ssh -i ~/.ssh/wpengine_ed25519 -o IdentitiesOnly=yes [email protected]

Windows: ssh -i C:\Users\YourUsername\.ssh\wpengine_ed25519 -o IdentitiesOnly=yes [email protected]

Adding your SSH key to the User Portal allows the key to be used on all environments your user account has access to in the User Portal.

A direct link to the page to add your SSH key to your account can be found at: https://my.wpengine.com/profile/ssh_keys

Or, to access this page manually, use the following steps:

1. Log in to the User Portal
2. Click the profile icon at the top right
3. Select SSH Keys
4. Click New SSH Key

6. Paste your Public Key into the field
   • To view the key contents on a Mac, run the following command in your terminal:
     cat ~/.ssh/wpengine_ed25519.pub
   • To view the key contents on Windows, run the following command in your terminal:
     type C:\Users\YourUsername\.ssh\wpengine_ed25519.pub
7. Click Add SSH Key

Once your SSH key is added it can be used for all environments to which your WP Engine User Portal user also has access. If you cannot see the environment in the User Portal, you cannot access it using SSH.

When connecting to SSH Gateway, you can use the following syntax from your terminal window. Be sure to replace the word environment with the unique WP Engine environment name (EX: environment.wpenginepowered.com).

ssh [email protected]

If you do not use an SSH config file, then you must specify which key your machine should use to authenticate the connection. In this example, the private key file is located at: ~/.ssh/wpengine_ed25519

ssh -i ~/.ssh/wpengine_ed25519 -o IdentitiesOnly=yes [email protected]

If you encounter any connection errors, please reference our Troubleshooting SSH Connection Issues guide.

Before you generate and add a new SSH key, you may first want to take a look at the SSH keys configured for your user profile. An existing key can be used easily, as long as it’s valid.

1. Open a Terminal or Command Prompt window from your computer
2. Change directory into the “.ssh” folder and list out the files.
   • Mac: cd ~/.ssh && ls
   • Windows: cd C:UsersUSERNAME.ssh && dir
     Note: Replace “USERNAME” with the username for your computer.
3. If the following two files exist, then you already have an SSH key configured for WP Engine on this machine:
   • wpengine_ed25519 and wpengine_ed25519.pub

If you do not have a key listed here, learn how to generate a key.

If  the two files above exist, validate that the key on your computer matches the key with WP Engine by comparing fingerprints.

1. From your computer, print the fingerprint for this key using the following command:
   • Mac: ssh-keygen -E md5 -lf ~/.ssh/wpengine_ed25519.pub
   • Windows: ssh-keygen -E md5 -lf C:UsersUSERNAME.sshwpengine_ed25519.pub
     Note: Replace “USERNAME” with the username for your computer.
2. Now, visit the following page in your User Portal:
   • https://my.wpengine.com/ssh_keys
3. Compare and confirm the fingerprints match.

If the fingerprints do not match, proceed to generating a new SSH key.

Users can remove their SSH key from WP Engine with the following steps.

1. Login to the User Portal
2. Click your name, at the top right
3. Select My Profile
4. Click SSH Keys
5. Select Remove next to the desired key

Users cannot directly delete SSH Keys of other users, as they’re attached to a WP Engine user profile. However the profile itself can have access granted or removed to the environments or account, which will in turn remove their SSH access to those environments.

Remove Access to Specific Environment(s)

Edit their user role on the account to “Partial”.

Select only the environments that you want the user to have access to.

Remove Access to all Environments on a WP Engine plan

Remove the user from the WP Engine plan entirely.

Now that you have successfully set up your keys and connected, it’s time to get started using SSH Gateway. You can use WP-CLI, bash loops, edit files using your favorite editor, and many other CLI tools. Be sure take a backup prior to making any changes.

For the below command examples, replace ENVIRONMENT with the name of the WP Engine environment that you’re connected to. Example: for mysite.wpenginepowered.com the environment name would be: mysite

After connecting to SSH, you will need to enter the root directory for your website to see and interact with your files. To do this, type:

cd sites/ENVIRONMENT

Or, you can enter the root directory of your website and list the files/directories there in a single command:

cd sites/ENVIRONMENT && ls

Learn more about using Vim in this tutorial program.

Edit a file named myfile.txt using vim:

vim myfile.txt

Enter MySQL command line and query your table storage engine for all tables:

First run:

mysql

Then run:

SELECT table_name, Engine FROM information_schema.tables WHERE table_schema='wp_environment'

SSH Gateway supports copying files to and from your environment with both scp and rsync. This guide will show you examples using both.

Before You Start

Two things about the gateway affect every file transfer:

Only /sites/environmentname/ persists. The SSH Gateway runs in a temporary sandbox container. Anything you write outside your site root, including your home directory, /tmp etc., is discarded the moment your session ends. Always use a full path under /sites/environmentname/ as the destination when you upload, and pull anything you want to keep down to your local machine before you disconnect.

Modern scp clients need the -O flag. Starting with OpenSSH 9.0, scp transfers files over the SFTP subsystem by default. Add the -O flag to make scp use the original SCP protocol, SSH Gateway supports. Check your client version with ssh -V; if it reports OpenSSH 9.0 or newer, you need -O.

Downloading a file from your environment

scp -O [email protected]:/sites/environment/backup.sql ~/Downloads/

To download a whole directory, add -r:

scp -O -r [email protected]:/sites/environment/wp-content/uploads/2026 ~/Downloads/

Uploading a file to your environment

scp -O ./local-script.php [email protected]:/sites/environment/_wpeprivate/

The _wpeprivate folder is a good destination for scripts and exports: it sits inside the persistent site root but is not web-accessible, so nothing you put there is exposed publicly.

Specifying your key

If you have not set up an SSH config file, name the key explicitly on every transfer, exactly as you would for ssh:

scp -O -i ~/.ssh/wpengine_ed25519 -o IdentitiesOnly=yes ./local-script.php [email protected]:/sites/environment/_wpeprivate/

IdentitiesOnly=yes matters. Without it your SSH client offers every key in your agent, and if it offers six or more unsuccessfully the SSH Gateway disconnects you – which usually shows up as Permission denied (publickey) even though your WP Engine key is perfectly valid. Setting this once in ~/.ssh/config avoids the problem for both ssh and scp:

Host *.ssh.wpengine.net
  User environment
  IdentityFile ~/.ssh/wpengine_ed25519
  IdentitiesOnly yes

With that in place, the command above shortens to the following format:

scp -O ./local-script.php [email protected]:/sites/environment/_wpeprivate/

Using rsync

rsync can be the better choice for large directories or repeated syncs, because it transfers only what has changed and can resume an interrupted transfer. 

Sync a local folder up to your environment:

rsync -rvP ./local-folder/ [email protected]:/sites/environment/wp-content/themes/mytheme/

Pull a folder down:

rsync -rvP [email protected]:/sites/environment/wp-content/uploads/ ./uploads/

Both directions are non-destructive by default: rsync adds and updates files but does not delete anything at the destination unless you explicitly pass the --delete flag.

Import a SQL file to your WordPress site’s database with WP-CLI:

wp db import mynewsqlfile.sql

Run database queries with WP-CLI by encasing the query in quotes:

wp db query "SELECT * FROM wp_users WHERE user_email='[email protected]';"

Update a plugin:

wp plugin update plugin-name

See if WordPress core files have been modified:

wp core verify-checksums

Add “administrator” capabilities to a user named “wpengine” with WP-CLI:

wp user add-cap wpengine administrator

Search-replace for olddomain.com to newdomain.com using precise (PHP-based search) on all tables with WP-CLI:

wp search-replace "olddomain.com" "newdomain.com" --all-tables --precise

Update WordPress to version 5.6 for multiple sites using a bash loop*:

for environment in environment1 environment2 environment3; do ssh $environment@$environment.ssh.wpengine.net "cd /sites/$environment && wp core update --version=5.6"; done

*You must run loops which iterate through multiple environments from your local machine instead of from the remote server.

The following are WP-CLI command syntax examples.

• The SSH key must begin with ssh-ed25519 with the entire key contents following on one single line when entered into the User Portal profile page.
• Each user can add multiple SSH keys to their User Portal profile.
• Each SSH key added to WP Engine is attached to a User Portal email address. If there are multiple computers from which a user will connect to SSH, it’s advised to use a separate key for each computer.
• Once your SSH key is added it can be used for all environments to which your WP Engine User Portal user also has access. If you cannot see the environment in the User Portal, you cannot access it using SSH.
• Each SSH Gateway user should add their own SSH key as a best practice. Do not share SSH keys between users or machines for security reasons.

• In general, you cannot use SSH to manage the aspects of your site that are in the User Portal (purge cache, create users, add a new environment).
• You cannot use SSH Gateway access to perform any actions that require root or sudo access, and cannot use it to access server logs.
• New or permanent files/directories can only be created in the /sites/environmentname/ directory. Newly created files outside of this path will disappear when your SSH session ends. Any scripts you create should be stored in your site’s _wpeprivate folder to ensure they’re secure, hidden and persistent.
• You can only remove files with the user “wpe-user” or “www-data”. You cannot remove files which are owned by “root” or “nobody”. Reset file permissions or reach out to Support if you have issues with these file permissions being set properly.
• The SSH Gateway connection limit is 5 per user. To serve customers at our scale we have several instances of our SSH Gateway service running and it is possible that occasionally customers will be able to initialize more than 5 connections.
  

When using SSH Gateway on WP Engine there are several potential issues outlined below.

A locale defines the user’s language, region, and character encoding settings. It dictates how special characters are displayed, how dates and times are formatted, and how files are sorted.If you only work with standard English text and filenames, you may never need to adjust these settings. However, if you see strange symbols (like ä or ?) instead of accented characters (like ä or ø), or if you are working with filenames containing international characters, you will need to configure your locale settings as described below to ensure proper display and compatibility.

Step 1: Configure your Terminal Emulator

First, ensure the terminal emulator you use to connect to SSH (such as Terminal on macOS, PuTTY on Windows, etc.) is configured to display text using UTF-8.

To test if your terminal is already configured correctly, run the following command:

printf "xC3xA4pfelnlxC3xB8rdagn"

Check the output. You should see:

äpfel
lørdag

If you see scrambled characters or question marks, you must check the preferences/settings of your terminal software and set the encoding to Unicode (UTF-8) before proceeding. This setting is usually found in your terminal’s Preferences or Settings menu, often under a Profiles, Terminal, or Encoding tab.

Step 2: Check the Current Server Locale

Once you verify that your terminal is configured to handle UTF-8 characters, the next step is to confirm that your server manages text in UTF-8 correctly.

By default, the SSH Gateway uses the C.UTF-8 locale. However, your SSH client can sometimes attempt to pass its own language settings to the server during the connection.After connecting to the SSH Gateway, run the command locale to see the active configuration.

Example output:

LANG=C.UTF-8
LANGUAGE=
LC_CTYPE="C.UTF-8"
LC_NUMERIC="C.UTF-8"
LC_TIME="C.UTF-8"
LC_ALL=

Look for UTF-8 or utf8 in the output. If the LANG variable is empty or set to POSIX, you may encounter issues with special characters.

Step 3: Setting a Different Locale

The SSH Gateway supports the most common UTF-8 locales. You can view a list of all available locales on the system by running:

locale -a

To switch to a specific locale for your session (for example, US English with UTF-8 support), set the environment variable LANG through the following command:

export LANG=en_US.utf8

Step 4: Verify the Fix

To confirm everything is working, create a temporary file using a special character in the name and verify that the system lists it correctly.

1. Set the language:
   export LANG=en_US.utf8
2. Create the file:
   touch äpfel.txt
3. List the file:
   ls
4. The output should display äpfel.txt clearly.

• File changes may take 5+ seconds to appear between the WordPress Admin Dashboard and the SSH session, and vice versa.
• In this case, simply wait a few seconds and then the changes should appear. Additionally, use an incognito window or clear the browser cache to see changes faster.
• Review our guide for purging caches.

• If receiving authentication errors when connecting, double-check the format of the username. The username must be formatted like so, where environment is replaced by the unique WP Engine environment name.
• environment@environment.ssh.wpengine.net

1. Log in to the User Portal
2. Click on the environment name to connect to
3. In the Overview section, locate SSH Login
4. Click the clipboard icon to copy the SSH login for easy pasting into the terminal

• Only files updated and saved within the /sites/environment/ directory will remain after the SSH session ends. A new SSH sandbox is created with each SSH session.
• To avoid this issue please ensure any new files or directories are created within the /sites/environment/ directory, as this is the root directory of the WordPress site.
• If creating scripts for use in SSH, please be sure these are placed in the _wpeprivate folder of the site, so these files will persist past the SSH session for future use.

• If opening a new file or performing an action with WP-CLI requires too many server resources, it is possible the action or the session itself may be killed. Actions should be batched into smaller sets to ensure minimal resource consumption.

• By default, the local machine will attempt to use all SSH keys present when connecting to the SSH Gateway. If 6 or more keys are presented unsuccessfully, the SSH Gateway will disconnect.
• To avoid this issue, use an SSH config file to designate which key file should be used with which hostname.

• In some rare cases, it may be possible for software deploys to break existing connections. If this happens, simply reconnect after a few minutes to continue work in SSH.

• If either of the following errors display when attempting to connect to SSH Gateway, the key does not match the type the client is looking for. This is because SSH-RSA SHA-1 has been deprecated.
  
  debug1: send_pubkey_test: no mutual signature algorithm

Permission denied (publickey). fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
  
  A possible resolution for this issue is to create the key using ED25519 instead:
  • To generate a new key in the supported format, use ssh-keygen -t ed25519 -f ~/.ssh/wpengine_ed25519
  • Use the new key files wpengine_ed25519 and wpengine_ed25519.pub

• When users are connecting to their SSH Gateway, there are two levels of authentication they pass through. The first determines whether the private and public keys match up and that the user has SSH access. If they do not, the user does not continue any further and receives the Permission denied (publickey) message.

1. Confirm the SSH key was added to the intended User Portal account
2. Confirm the SSH connection command is entered correctly, and that there are no typos or missing letters
3. Is there an SSH config file? Run cat ~/.ssh/config to check.
   • If yes, open it and ensure there is an entry in the SSH config file for *.wpengine.net mapped to the correct wpengine_ed25519 key file name and that everything is spelled correctly.
   • If there is no SSH config, set one up using this guide. This will ensure the machine uses the correct key when connecting.

A number of other error messages may display, depending on the error condition: