TRAMP supports starting new running processes on the remote host for discovering remote file names. Emacs packages on the remote host need no specific modifications for TRAMP’s use.

This type of integration does not work with the ftp method, and does not support the pty association as specified in start-file-process.

process-file and start-file-process work on the remote host when the variable default-directory is remote:

(let ((default-directory "/ssh:remote.host:"))
  (start-file-process "grep" (get-buffer-create "*grep*")
                      "/bin/sh" "-c" "grep -e tramp *"))

Remote processes do not apply to GVFS (see GVFS-based methods) because the remote file system is mounted on the local host and TRAMP just accesses by changing the default-directory.

TRAMP starts a remote process when a command is executed in a remote file or directory buffer. As of now, these packages have been integrated to work with TRAMP: compile.el (commands like compile and grep) and gud.el (gdb or perldb).

For TRAMP to find the command on the remote, it must be accessible through the default search path as setup by TRAMP upon first connection. Alternatively, use an absolute path or extend tramp-remote-path (see Remote programs):

(add-to-list 'tramp-remote-path "~/bin")
(add-to-list 'tramp-remote-path "/appli/pub/bin")

Customize user option tramp-remote-process-environment to suit the remote program’s environment for the remote host. tramp-remote-process-environment is a list of strings structured similar to process-environment, where each element is a string of the form ‘ENVVARNAME=VALUE’.

To avoid any conflicts with local host environment variables set through local configuration files, such as ~/.profile, use ‘ENVVARNAME=’ to unset them for the remote environment.

(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java")

Modifying or deleting already existing values in the tramp-remote-process-environment list may not be feasible on restricted remote hosts. For example, some system administrators disallow changing HISTORY environment variable. To accommodate such restrictions when using TRAMP, fix the tramp-remote-process-environment by the following code in the local .emacs file:

(let ((process-environment tramp-remote-process-environment))
  (setenv "HISTORY" nil)
  (setq tramp-remote-process-environment process-environment))

Setting the ENV environment variable instructs some shells to read an initialization file. Per default, TRAMP has disabled this. You could overwrite this behavior by evaluating

(let ((process-environment tramp-remote-process-environment))
  (setenv "ENV" "$HOME/.profile")
  (setq tramp-remote-process-environment process-environment))

In addition to tramp-remote-process-environment, you can set environment variables for individual remote process calls by let-binding process-environment. TRAMP applies any entries not present in the global default value of process-environment (overriding tramp-remote-process-environment settings, if they conflict). For example:

(let ((process-environment (cons "HGPLAIN=1" process-environment)))
  (process-file …))

Let-binding in this way works regardless of whether the process to be called is local or remote, since TRAMP would add just the HGPLAIN setting and local processes would take whole value of process-environment along with the new value of HGPLAIN.

For integrating other Emacs packages so TRAMP can execute remotely, please file a bug report. See Bug Reports.

5.5.1 Running remote programs that create local X11 windows

To allow a remote program to create an X11 window on the local host, set the DISPLAY environment variable for the remote host as follows in the local .emacs file:

(add-to-list 'tramp-remote-process-environment
             (format "DISPLAY=%s" (getenv "DISPLAY")))

(getenv "DISPLAY") should return a recognizable name for the local host that the remote host can redirect X11 window interactions. If querying for a recognizable name is not possible for whatever reason, then replace (getenv "DISPLAY") with a hard-coded, fixed name. Note that using :0 for X11 display name here will not work as expected.

An alternate approach is specify ForwardX11 yes or ForwardX11Trusted yes in ~/.ssh/config on the local host.

5.5.2 Running shell on a remote host

Set explicit-shell-file-name to the appropriate shell name when using TRAMP between two hosts with different operating systems, such as ‘windows-nt’ and ‘gnu/linux’. This option ensures the correct name of the remote shell program.

When explicit-shell-file-name is equal to nil, calling shell interactively will prompt for a shell name.

Starting with Emacs 26, you could use connection-local variables for setting different values of explicit-shell-file-name for different remote hosts.

(connection-local-set-profile-variables
  'remote-bash
  '((explicit-shell-file-name . "/bin/bash")
    (explicit-bash-args . ("-i"))))

(connection-local-set-profile-variables
  'remote-ksh
  '((explicit-shell-file-name . "/bin/ksh")
    (explicit-ksh-args . ("-i"))))

(connection-local-set-profiles
  '(:application tramp :protocol "ssh" :machine "localhost")
  'remote-bash)

(connection-local-set-profiles
  `(:application tramp :protocol "sudo"
    :user "root" :machine ,(system-name))
  'remote-ksh)

5.5.3 Running shell-command on a remote host

shell-command executes commands synchronously or asynchronously on remote hosts and displays output in buffers on the local host. Example:

tail command outputs continuously to the local buffer, *Async Shell Command*

shell-command uses the variables shell-file-name and shell-command-switch in order to determine which shell to run. For remote hosts, their default values are /bin/sh and -c, respectively (except for the adb method, which uses /system/bin/sh). Like the variables in the previous section, these variables can be changed via connection-local variables.

If Emacs supports the variable async-shell-command-width (since Emacs 27.1), TRAMP cares about its value for asynchronous shell commands. It specifies the number of display columns for command output. For synchronous shell commands, a similar effect can be achieved by adding the environment variable COLUMNS to tramp-remote-process-environment.

5.5.4 Running eshell on a remote host

TRAMP is integrated into eshell.el, which enables interactive eshell sessions on remote hosts at the command prompt. You must add the module eshell-tramp to eshell-modules-list. Here’s a sample interaction after opening M-x eshell RET on a remote host:

~ $ cd /sudo::/etc RET
/sudo:root@host:/etc $ hostname RET
host
/sudo:root@host:/etc $ id RET
uid=0(root) gid=0(root) groups=0(root)
/sudo:root@host:/etc $ find-file shadow RET
#<buffer shadow>
/sudo:root@host:/etc $

eshell added custom su and sudo commands that set the default directory correctly for the *eshell* buffer. TRAMP silently updates tramp-default-proxies-alist with an entry for this directory (see Multi-hops):

~ $ cd /ssh:user@remotehost:/etc RET
/ssh:user@remotehost:/etc $ find-file shadow RET
File is not readable: /ssh:user@remotehost:/etc/shadow
/ssh:user@remotehost:/etc $ sudo find-file shadow RET
#<buffer shadow>

/ssh:user@remotehost:/etc $ su - RET
/su:root@remotehost:/root $ id RET
uid=0(root) gid=0(root) groups=0(root)
/su:root@remotehost:/root $

5.5.5 Running a debugger on a remote host

gud.el provides a unified interface to symbolic debuggers TRAMP can run debug on remote hosts by calling gdb with a remote file name:

Since the remote gdb and gdb-inferior processes do not belong to the same process group on the remote host, there will be a warning, which can be ignored:

As consequence, there will be restrictions in I/O of the process to be debugged.

Relative file names are based on the remote default directory. When myprog.pl exists in /ssh:host:/home/user, valid calls include:

Just the local part of a remote file name, such as

perl -d
/home/user/myprog.pl

, is not possible.

Arguments of the program to be debugged must be literal, can take relative or absolute paths, but not remote paths.

5.5.6 Running remote processes on MS Windows hosts

winexe runs processes on a remote MS Windows host, and TRAMP can use it for process-file and start-file-process.

tramp-smb-winexe-program specifies the local winexe command. Powershell V2.0 on the remote host is required to run processes triggered from TRAMP.

explicit-shell-file-name and explicit-*-args have to be set properly so M-x shell RET can open a proper remote shell on a MS Windows host. To open cmd, set it as follows:

5.5 Integration with other Emacs packages

5.5.1 Running remote programs that create local X11 windows

5.5.2 Running `shell` on a remote host

5.5.3 Running `shell-command` on a remote host

5.5.4 Running `eshell` on a remote host

5.5.5 Running a debugger on a remote host

5.5.6 Running remote processes on MS Windows hosts

5.5 Integration with other Emacs packages

5.5.1 Running remote programs that create local X11 windows

5.5.2 Running shell on a remote host

5.5.3 Running shell-command on a remote host

5.5.4 Running eshell on a remote host

5.5.5 Running a debugger on a remote host

5.5.6 Running remote processes on MS Windows hosts

5.5.2 Running `shell` on a remote host

5.5.3 Running `shell-command` on a remote host

5.5.4 Running `eshell` on a remote host