Remote SSH

The Remote SSH tab connects any project to a remote server and opens an SSH terminal to it. In DDEV projects, Logs, log monitoring and the Scratchpad code runner also use this connection.

Open the Remote SSH Tab

Open the Remote SSH tab of a project. The toolbar shows the connection name and the remote project root.

You can also open it from the Remote server card on the Overview tab:

• Open remote shell: opens the Remote SSH tab.
• Edit connection: opens the Remote SSH tab with the connection form. When there is no connection, the link is Set up connection.

The links in Logs and the Scratchpad that set up SSH also open the Remote SSH tab.

NOTE

Only remote servers that run Linux are supported.

Set Up a Connection

When there is no connection, the Remote SSH tab shows Connect to your server.

Configured host

1. Select Configured host.
2. Select a host from your SSH config file.
3. Click Save.

SSH configuration

1. Select SSH configuration.
2. Type the Hostname (domain or IP address), the Username and the Port (default 22).
3. Optional: check Save in ~/.ssh/config to add the connection to your SSH config file.
4. Click Save.

When you open this form, DevWorkspace Pro reads your clipboard. If it finds an SSH connection string, for example user@hostname:port or ssh user@hostname, it asks if it can use it to fill the form.

Optional fields

• Remote Project Root: the project folder on the server. The SSH terminal starts in this folder. Logs and the Scratchpad need it.
• Private Key Path: the key for remote logs, log monitoring and the Scratchpad. If you leave it empty, DevWorkspace Pro uses the IdentityFile of the host in your SSH config.

The SSH Terminal

When a connection is saved, the Remote SSH tab shows a terminal that runs ssh to your server. The toolbar has:

• The keep-alive status
• Reconnect, to start a new session
• Edit SSH, to change the connection
• Detach, to remove the connection from the project. Optional: check Also remove this entry from SSH config file.

Session

The SSH session stays open when you go to a different tab or project. When you come back, the terminal shows the same session with its output.

When you rename or delete the project, or when you change or detach the connection, DevWorkspace Pro closes the session.

Disconnected

When the SSH connection closes or the remote shell exits, the toolbar shows Disconnected, and the terminal shows SSH session ended. Nothing that you type there runs. The session never changes to a shell on your computer.

Click Reconnect to start a new SSH session.

Keep-alive

DevWorkspace Pro keeps the connection alive. If the server stops replying, the connection closes, and the toolbar shows Disconnected.

You can also make DevWorkspace Pro send pings when the terminal is inactive, so the server does not close the connection. Open Preferences → SSH:

Setting	Default	Range
Enable SSH Keep-Alive	Off
Inactivity Timeout (seconds)	60	10 to 600
Keep-Alive Ping Interval (seconds)	30	5 to 300
Keep-Alive Max Duration (minutes)	60	1 to 480

SSH Config File

The default file is ~/.ssh/config. To use a different file, change SSH Config File Path in Preferences → SSH.

When you save a new connection to the file, DevWorkspace Pro adds a host block like this:

# Added by DevWorkspace Pro
Host ddev-project-name
  HostName your-server.com
  User your-username
  Port 22

To use a specific key for a server, add IdentityFile to the host block:

Host ddev-your-project
  HostName your-server.com
  User your-username
  IdentityFile ~/.ssh/specific_key

Troubleshooting

Connection problems

1. Connect to the same server with ssh in your system terminal.
2. For the SSH terminal, add your key to your SSH agent: ssh-add ~/.ssh/your_key.
3. For remote logs, log monitoring and the Scratchpad, make sure that Private Key Path or the IdentityFile of the host points to your key. These features read the key file. They do not use the SSH agent.

"Unable to start subsystem: sftp" error

The Scratchpad and the log Download button use SFTP. This error occurs when the SSH server does not have SFTP enabled.

1. Find out if SFTP is configured:

   ssh user@yourserver "grep -i sftp /etc/ssh/sshd_config"

2. If there is no SFTP subsystem, add it to /etc/ssh/sshd_config:

   # Most Linux systems:
   Subsystem sftp /usr/lib/openssh/sftp-server
   
   # CentOS, RHEL and cPanel servers:
   Subsystem sftp /usr/libexec/openssh/sftp-server

3. If the sftp-server path is different on your server, find it:

   find /usr -name sftp-server 2>/dev/null

4. Restart the SSH service:

   sudo systemctl restart sshd
   # or on older systems:
   sudo service sshd restart

5. Test the connection:

   sftp user@yourserver