Set Up and Connect to 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 like: WP CLI, MySQL command line, bash, and Composer to manage your website. With WP Engine’s SSH Gateway you can connect to a container that sits like a sidecar next to your website, and allows you to access your website’s filesystem and database. SSH Gateway uses key-based authentication for even greater security than a simple username and password combination.

About SSH Gateway

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. It 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 a sandboxed 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.

Create SSH Key

We highly advise configuring a SSH config file before proceeding, as this will mitigate many potential issues down the road.

Add SSH Key

Adding your SSH key to the User Portal allows the key to be used on all environments your email has access to in the User Portal. This makes it simple and easy to ensure you have SSH access ready to go when it’s needed for past and future environments.

After your key has been added to the User Portal, the command you must use to connect using SSH will require that you specify the environment name to ensure you enter the appropriate website.

A direct link to the page to add your SSH key to your account can be found at:

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
  1. Paste your Public Key * into the field
    • To view the key contents, run cat ~/.ssh/
  2. 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.

Connect to SSH Gateway

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:


If you do not use a 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

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

Using SSH

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.


The first thing you should do when connecting to SSH Gateway is change directories into the install’s root. Only files added to the root directory or lower will persist, any files changes above the root will be removed at the end of the session.

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

Be sure to replace environment with your WP Engine environment name or update the file name and path to the appropriate location.

Example Commands

Below are some examples of commands you can use once within the root directory of your install:

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

wp db import mynewsqlfile.sql

Install and activate the WooCommerce plugin with WP-CLI:

wp plugin install woocommerce --activate

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

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

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 to using precise (PHP-based search) on all tables with WP-CLI:

wp search-replace “” “” --all-tables --precise

Sync all the files from folder1 to folder2 using rsync (non-destructive):

rsync -rvP folder1/ folder2/

Sync example.png on your local machine to folder4 on your website (non-destructive):

rsync example.png

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'

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

for environment in environment1 environment2 environment3; do ssh $environment@$ "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.

SSH Gateway Limitations

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.

Additional Information

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

Troubleshooting SSH

For more information to troubleshoot SSH connection issues, see our SSH Gateway Issues guide here.

NEXT STEP: Learn how to connect to SSH Gateway

Code-level performance analytics

Application Performance provides real-time, code-level visibility to help you troubleshoot faster, optimize WordPress experiences, and increase development agility.