This tutorial shows you how to set up the Chrome Remote Desktop service on a Debian Linux virtual machine (VM) instance on Compute Engine. For separate instructions for Windows VMs, see Windows virtual machines. Chrome Remote Desktop lets you remotely access applications with a graphical user interface from a local computer or mobile device.
When following this tutorial, the default firewall rules allow Chrome Remote Desktop connections; you don't need to configure any additional firewall rules. SSH access is required only for the initial setup.
The VM does need access to the internet (either with an external IP address or through Cloud NAT), and you use your Google Account for authentication and authorization.
This tutorial assumes that you are familiar with the Linux command line and with installing Debian packages.
For information about other options for creating virtual workstations, see Creating a virtual workstation.
Objectives
- Create a headless Compute Engine VM instance to run Chrome Remote Desktop on.
- Install and configure the Chrome Remote Desktop service on the VM instance.
- Set up an X Window System desktop environment in the VM instance.
- Connect from your local computer to the desktop environment on the VM instance.
Costs
This tutorial uses billable components of Google Cloud, including:
- Compute Engine
Use the Pricing Calculator to generate a cost estimate based on your projected usage.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Compute Engine API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Compute Engine API.
-
Make sure that you have the following role or roles on the project: roles/compute.admin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role colunn to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- In the Select a role list, select a role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
- You use the Google Chrome browser on your local machine.
When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, see Clean up.
Create a Compute Engine instance
For the purposes of this tutorial, the default machine type with a Debian Linux boot disk is used. If you are using this for your own environment, you may want to adjust the machine type, name, region, boot disk size, or other settings.
In the Google Cloud console, go to the VM Instances page.
Click Create.
Set the instance name to
crdhost
.Click Create.
It takes a few moments to create your instance.
After the instance has been created, connect to your new instance by clicking SSH in the instance list:
Install Chrome Remote Desktop on the VM instance
In the SSH window for your VM instance, add the Debian Linux Chrome Remote Desktop repository to your
apt
package list, and install thechrome-remote-desktop
package.curl https://dl.google.com/linux/linux_signing_key.pub \ | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/chrome-remote-desktop.gpg echo "deb [arch=amd64] https://dl.google.com/linux/chrome-remote-desktop/deb stable main" \ | sudo tee /etc/apt/sources.list.d/chrome-remote-desktop.list sudo apt-get update sudo DEBIAN_FRONTEND=noninteractive \ apt-get install --assume-yes chrome-remote-desktop
The
DEBIAN_FRONTEND=noninteractive
parameter suppresses a prompt to configure a layout for a keyboard that would be directly connected to the VM instance.
Install an X Windows System desktop environment
You need to install an X Window System desktop environment and window manager for Chrome Remote Desktop to use. Common options are:
You can use other desktop environments, but Chrome Remote Desktop does not support 3D graphics acceleration. If you do choose a desktop environment that uses 3D graphics acceleration, you need to disable that feature, or the remote desktop service won't start.
For remote connections over slower networks we recommended Xfce because it has minimal graphical elements and few animations.
Xfce
In the SSH window connected to your VM instance, install the Xfce desktop environment and basic desktop components:
sudo DEBIAN_FRONTEND=noninteractive \ apt install --assume-yes xfce4 desktop-base dbus-x11 xscreensaver
XScreenSaver is required because the Xfce default screen locker (Light Locker) doesn't work with Chrome Remote Desktop (Light Locker displays a blank screen that cannot be unlocked).
Configure Chrome Remote Desktop to use Xfce by default:
sudo bash -c 'echo "exec /etc/X11/Xsession /usr/bin/xfce4-session" > /etc/chrome-remote-desktop-session'
Because there is no display connected to your instance, disable the display manager service on your instance:
sudo systemctl disable lightdm.service
Optional: Install the full suite of Linux desktop applications, including the Firefox browser, LibreOffice office application suite, and the Evince PDF viewer:
sudo apt install --assume-yes task-xfce-desktop
Optional: Install the Chrome browser on your instance:
curl -L -o google-chrome-stable_current_amd64.deb \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt install --assume-yes --fix-broken ./google-chrome-stable_current_amd64.deb
Cinnamon
In the SSH window connected to your VM instance, install the Cinnamon desktop environment and basic desktop components:
sudo DEBIAN_FRONTEND=noninteractive \ apt install --assume-yes cinnamon-core desktop-base dbus-x11
Set your Chrome Remote Desktop session to use Cinnamon in 2D mode (which does not use 3D graphics acceleration) by default:
sudo bash -c 'echo "exec /etc/X11/Xsession /usr/bin/cinnamon-session-cinnamon2d" > /etc/chrome-remote-desktop-session'
Optionally, install the full suite of Linux desktop applications, including the Firefox browser, the LibreOffice office application suite, and the Evince PDF viewer:
sudo apt install --assume-yes task-cinnamon-desktop
Optional: Install the Chrome browser on your instance:
curl -L -o google-chrome-stable_current_amd64.deb \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt install --assume-yes --fix-broken ./google-chrome-stable_current_amd64.deb
Gnome
In the SSH window connected to your VM instance, install the full Gnome desktop environment, including the Firefox browser, the LibreOffice office application suite, and the Evince PDF viewer:
sudo DEBIAN_FRONTEND=noninteractive \ apt install --assume-yes task-gnome-desktop
Set your Chrome Remote Desktop session to use Gnome
sudo bash -c 'echo "exec /etc/X11/Xsession /usr/bin/gnome-session" > /etc/chrome-remote-desktop-session'
Disable the Gnome display manager service on your instance, because it conflicts with the Chrome Remote Desktop service.
sudo systemctl disable gdm3.service sudo reboot
This command reboots the VM.
Reconnect through SSH before continuing.
Optional: Install the Chrome browser on your instance:
curl -L -o google-chrome-stable_current_amd64.deb \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt install --assume-yes --fix-broken ./google-chrome-stable_current_amd64.deb
Gnome-Classic
In the SSH window connected to your VM instance, install the full Gnome desktop environment, including the Firefox browser, the LibreOffice office application suite, and the Evince PDF viewer:
sudo DEBIAN_FRONTEND=noninteractive \ apt install --assume-yes task-gnome-desktop
The
DEBIAN_FRONTEND=noninteractive
parameter suppresses a prompt to configure a layout for a keyboard that would be directly connected to the VM instance.Set your Chrome Remote Desktop session to use the Gnome-Classic desktop:
sudo bash -c 'echo "exec /etc/X11/Xsession /usr/bin/gnome-session-classic" > /etc/chrome-remote-desktop-session'
Disable the Gnome display manager service on your instance, because it conflicts with the Chrome Remote Desktop service.
sudo systemctl disable gdm3.service sudo reboot
This command reboots the VM.
Reconnect through SSH before continuing.
Optional: Install the Chrome browser on your instance:
curl -L -o google-chrome-stable_current_amd64.deb \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt install --assume-yes --fix-broken ./google-chrome-stable_current_amd64.deb
KDE Plasma
In the SSH window connected to your VM instance, install the full KDE Plasma desktop environment, including the Firefox browser, the LibreOffice office application suite, and the Evince PDF viewer:
sudo DEBIAN_FRONTEND=noninteractive \ apt install --assume-yes task-kde-desktop
The
DEBIAN_FRONTEND=noninteractive
parameter suppresses a prompt to configure a layout for a keyboard that would be directly connected to the VM instance.Set your Chrome Remote Desktop session to use KDE Plasma
sudo bash -c 'echo "exec /etc/X11/Xsession /usr/bin/startplasma-x11" > /etc/chrome-remote-desktop-session'
Optional: Install the Chrome browser on your instance:
curl -L -o google-chrome-stable_current_amd64.deb \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt install --assume-yes --fix-broken ./google-chrome-stable_current_amd64.deb
Configure and start the Chrome Remote Desktop service
To start the remote desktop server, you need to have an authorization key for the Google Account that you want to use to connect to it:
In the Google Cloud console, go to the VM Instances page:
Connect to your instance by clicking the SSH button.
On your local computer, using the Chrome browser, go to the Chrome Remote Desktop command line setup page:
If you're not already signed in, sign in with a Google Account. This is the account that will be used for authorizing remote access.
On the Set up another computer page, click Begin.
Click Authorize.
You need to allow Chrome Remote Desktop to access your account. If you approve, the page displays a command line for Debian Linux that looks like the following:
DISPLAY= /opt/google/chrome-remote-desktop/start-host \ --code="4/xxxxxxxxxxxxxxxxxxxxxxxx" \ --redirect-url="https://remotedesktop.google.com/_/oauthredirect" \ --name=$(hostname)
You use this command to set up and start the Chrome Remote Desktop service on your VM instance, linking it with your Google Account using the authorization code.
Copy the command to the SSH window that's connected to your instance, and then run the command.
When you're prompted, enter a 6-digit PIN. This number will be used for additional authorization when you connect later.
You might see errors like
No net_fetcher
orFailed to read
. You can ignore these errors.Verify that the service is running using the following command.
sudo systemctl status chrome-remote-desktop@$USER
If the service is running, you see output that includes the state
active
:chrome-remote-desktop.service - LSB: Chrome Remote Desktop service Loaded: loaded (/lib/systemd/system/chrome-remote-desktop@USER.service; enabled; vendor preset: enabled) Active: active (running) since DATE_TIME; ELAPSED_TIME
Connect to the VM instance
You can connect to the VM instance using the Chrome Remote Desktop web application.
On your local computer, go to the Chrome Remote Desktop website.
Click Access my computer.
If you're not already signed in to Google, sign in with the same Google Account that you used to set up the Chrome Remote Desktop service.
You see your new VM instance
crdhost
in the Remote Devices list.Click the name of the remote desktop instance.
When you're prompted, enter the PIN that you created earlier, and then click the arrow button to connect.
You are now connected to the desktop environment on your remote Compute Engine instance.
If you are prompted, always allow the Remote Desktop application to read your clipboard and let you copy and paste between local and remote applications.
If you installed the Xfce desktop, the first time you connect, you are prompted to set up the desktop panels. Click Use Default Config to get the standard taskbar at the top and the quick launch panel at the bottom.
Improve the remote desktop experience
This section provides instructions for changing settings in order to improve the remote desktop experience.
Install the Remote Desktop Chrome app
The Remote Desktop Chrome app gives a separate windowed experience and allows keyboard shortcuts that would normally be intercepted by Chrome to be used on the remote system.
If this app is not installed, do the following:
- Open the Session Options panel using the button chevron_left that appears when you move the mouse to the side of the window.
- In the Install App section, click Begin.
- Click Install.
The remote desktop session reopens in its own application window.
You can move any remote desktop sessions from a Chrome tab to the app window by clicking the Open With open_in_new icon in the address bar.
Disable animations and effects in Cinnamon
The Cinnamon desktop uses several graphical features and animations, such as semi-transparent windows and menus that fade in and out. Because these animations take more time to render over a remote connection, it can make the user interface feel slow.
To disable these effects:
In the Cinnamon desktop, select Menu > Preferences > Effects.
Disable each of the effects:
Set a user password
The user account created by Compute Engine doesn't have a password. However, several desktop environments require one for unlocking screensavers and authorizing administrative actions. It is therefore important to set a password for your user:
- Connect to the instance using SSH, as you did when you first set up the instance.
Create a password for the user:
sudo passwd $(whoami)
Disable screensavers and lock screens
Because you're accessing your desktop from a remote computer, it's normally not necessary to use a screensaver or screen locker, so you can disable these.
Xfce
- In the Applications menu, select Settings > Screensaver.
- Set Mode to Disable Screen Saver.
Cinnamon
- In the desktop, select Menu > Preferences > Screensaver.
- In the Settings tab, set Delay to Never and disable the following two Lock settings to lock the screen automatically.
Gnome
- In the desktop, click Activities and type
Settings
. - Select the Settings application.
- In the Settings application, select Privacy > Screen Lock.
- Disable Automatic Screen Lock and close the dialog.
- Select Devices > Keyboard.
- In the list of keyboard shortcuts, go to the System section, and then click Lock Screen.
- Press the
Backspace
key to disable the shortcut, and then click Set. - Select Power and set Blank Screen to Never.
Gnome-Classic
- In the desktop, select Applications > System Tools > Settings.
- In the Settings application, select Privacy > Screen Lock.
- Disable Automatic Screen Lock and close the dialog.
- Select Devices > Keyboard.
- In the list of keyboard shortcuts, go to the System section and click Lock Screen.
- Press the
Backspace
key to disable the shortcut, and then click Set. - Select Power and set Blank Screen to Never.
KDE Plasma
- In the desktop, click the KDE menu button, and then type
Screen Locking
. - Select the Screen Locking application.
- In the Configure Screen Locking application, disable Lock Screen Automatically after and click the button to clear the keyboard shortcut.
- Click OK.
Increase the desktop resolution
If you have an ultra high-resolution monitor, you might find that the default maximum remote desktop size of 1600 x 1200 is too small. If so, you can increase it to the resolution of your monitor.
- Use SSH to connect to the instance.
Set the
CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES
environment variable to include the resolution of your monitor:echo "export CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES=1600x1200,3840x2560" \ >> ~/.profile
Restart the service:
sudo systemctl restart chrome-remote-desktop@$USER
Enable advanced video codec:
The AV1 codec with High Quality color gives improved picture quality and allows better encoding of pure color information (such as text):
- Open the Session Options panel using the button chevron_left that appears when you move the mouse to the side of the window.
- In the Video Codec field, select AV1
- Ensure that High-quality color field is enabled.
Choose a different desktop environment
In the preceding section, you set a default desktop environment in the global
/etc/chrome-remote-desktop-session
configuration file. You can also choose a
different desktop environment (if it's installed) by specifying it in the
.chrome-remote-desktop-session
configuration file in your home directory:
Xfce
echo "exec /etc/X11/Xsession /usr/bin/xfce4-session" > ~/.chrome-remote-desktop-session
Cinnamon
echo "exec /etc/X11/Xsession /usr/bin/cinnamon-session-cinnamon2d" > ~/.chrome-remote-desktop-session
Gnome
echo "exec /etc/X11/Xsession /usr/bin/gnome-session" > ~/.chrome-remote-desktop-session
Gnome-Classic
echo "exec /etc/X11/Xsession /usr/bin/gnome-session-classic" > ~/.chrome-remote-desktop-session
KDE Plasma
echo "exec /etc/X11/Xsession /usr/bin/startplasma-x11" > ~/.chrome-remote-desktop-session
After you make this change, restart the service so the change takes effect:
sudo systemctl restart chrome-remote-desktop@$USER
As mentioned before, Chrome Remote Desktop does not support 3D graphics acceleration. Therefore, for any desktop environments that uses these features, you need disable 3D graphics, or the session won't start.
Automate the installation process
When you need to set up multiple machines with Chrome Remote Desktop, the manual installation steps can become repetitive. You can use a custom startup script to automate this process, using the following procedure.
For the purposes of this tutorial, the default machine type with a Debian Linux boot disk is used. If you are using this for your own environment, you may want to adjust the machine type, name, region, boot disk size, or other settings.
In the Google Cloud console, go to the VM Instances page:
Click Create Instance.
Set the instance name to
crdhost-autoinstall
.Scroll to, and expand the Advanced Options section.
Expand the Management section.
Copy the following shell script and paste it into the Automation/Startup Script field:
#!/bin/bash -x # # Startup script to install Chrome remote desktop and a desktop environment. # # See environmental variables at then end of the script for configuration # function install_desktop_env { PACKAGES="desktop-base xscreensaver dbus-x11" if [[ "$INSTALL_XFCE" != "yes" && "$INSTALL_CINNAMON" != "yes" ]] ; then # neither XFCE nor cinnamon specified; install both INSTALL_XFCE=yes INSTALL_CINNAMON=yes fi if [[ "$INSTALL_XFCE" = "yes" ]] ; then PACKAGES="$PACKAGES xfce4" echo "exec xfce4-session" > /etc/chrome-remote-desktop-session [[ "$INSTALL_FULL_DESKTOP" = "yes" ]] && \ PACKAGES="$PACKAGES task-xfce-desktop" fi if [[ "$INSTALL_CINNAMON" = "yes" ]] ; then PACKAGES="$PACKAGES cinnamon-core" echo "exec cinnamon-session-cinnamon2d" > /etc/chrome-remote-desktop-session [[ "$INSTALL_FULL_DESKTOP" = "yes" ]] && \ PACKAGES="$PACKAGES task-cinnamon-desktop" fi DEBIAN_FRONTEND=noninteractive \ apt-get install --assume-yes $PACKAGES $EXTRA_PACKAGES systemctl disable lightdm.service } function download_and_install { # args URL FILENAME if [[ -e "$2" ]] ; then echo "cannot download $1 to $2 - file exists" return 1; fi curl -L -o "$2" "$1" && \ apt-get install --assume-yes --fix-broken "$2" && \ rm "$2" } function is_installed { # args PACKAGE_NAME dpkg-query --list "$1" | grep -q "^ii" 2>/dev/null return $? } # Configure the following environmental variables as required: INSTALL_XFCE=yes INSTALL_CINNAMON=yes INSTALL_CHROME=yes INSTALL_FULL_DESKTOP=yes # Any additional packages that should be installed on startup can be added here EXTRA_PACKAGES="less bzip2 zip unzip tasksel wget" apt-get update if ! is_installed chrome-remote-desktop; then if [[ ! -e /etc/apt/sources.list.d/chrome-remote-desktop.list ]]; then echo "deb [arch=amd64] https://dl.google.com/linux/chrome-remote-desktop/deb stable main" \ | tee -a /etc/apt/sources.list.d/chrome-remote-desktop.list fi apt-get update DEBIAN_FRONTEND=noninteractive \ apt-get install --assume-yes chrome-remote-desktop fi install_desktop_env [[ "$INSTALL_CHROME" = "yes" ]] && ! is_installed google-chrome-stable && \ download_and_install \ https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb \ /tmp/google-chrome-stable_current_amd64.deb echo "Chrome remote desktop installation completed"
This script performs the following tasks each time the machine is rebooted:
- If the remote desktop package is not installed:
- Adds the Chrome Remote Desktop Debian package repository
- Installs the Chrome Remote Desktop package and dependencies.
- Installs the Xfce or Cinnamon desktop environments (depending on the script settings).
- If the full desktop environment option is enabled, installs the necessary packages.
- If the Google Chrome browser option is enabled and is not installed:
- Downloads Google Chrome package.
- Installs Google Chrome and its dependent packages.
- If the remote desktop package is not installed:
Click Create.
It takes a few moments to create your instance, and on first run with all the options enabled, the script can take up to 10 minutes to complete the installation.
To monitor progress, connect to the VM instance using SSH, and in the terminal of the instance, run the following command:
sudo journalctl -o cat -f _SYSTEMD_UNIT=google-startup-scripts.service
This command shows the output from the startup script. When the script has finished, you see the following:
INFO startup-script: Chrome remote desktop installation completed INFO startup-script: Return code 0. INFO Finished running startup scripts.
This script only installs the required packages; you still need to configure the Remote Desktop Service for your user, as described previously.
There are various ways to specify a startup script when creating a new VM instance:
- Pasting it into the Google Cloud console (as shown earlier).
- Storing it as a file on a local machine, and using the
--metadata-from-file
flag when you create the instance using the Google Cloud CLI. - Storing it in a Cloud Storage bucket and specifying the URL to the object—either in the console or in the gcloud CLI.
For more information on the alternative methods of how to configure the startup script, see Running Startup scripts in the Compute Engine documentation.
Troubleshooting
This section provides troubleshooting advice for this guide.
Check the status of the Chrome Remote Desktop service
If at any point the Chrome Remote Desktop service is not responding, you can check its status by using SSH to connect to the instance and running the following command:
sudo systemctl status chrome-remote-desktop@$USER
If the service is running, you see output that includes the state active
:
chrome-remote-desktop.service - LSB: Chrome Remote Desktop service Loaded: loaded (/lib/systemd/system/chrome-remote-desktop@USER.service; enabled; vendor preset: enabled) Active: active (running) since DATE_TIME; ELAPSED_TIME
To restart the service, use the following command in the SSH window:
sudo systemctl restart chrome-remote-desktop@$USER
Get log and error information
Chrome Remote Desktop writes log information to the system journal:
journalctl SYSLOG_IDENTIFIER=chrome-remote-desktop # All logs
journalctl SYSLOG_IDENTIFIER=chrome-remote-desktop -e # Most recent logs
journalctl SYSLOG_IDENTIFIER=chrome-remote-desktop -b # Logs since reboot
You can check these log files for error messages.
Re-enable the service
If you have mistakenly disabled connections to the remote instance in the client app, you can reconfigure the service and re-enable it by following the instructions in Configure and start the Chrome Remote Desktop service.
Check the global and user-specific session configuration files.
Check the contents of the global
/etc/chrome-remote-desktop-session
configuration file and the
user-specific ~/.chrome-remote-desktop-session
configuration file and confirm
that the specified desktop environments are installed.
Clean up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.
Delete the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete the Compute Engine instance
As an alternative to deleting the entire project, you can delete the VM instance you created for this tutorial:
In the Google Cloud console, go to the VM Instances page:
Select the checkbox next to the instance name you created earlier (
crdhost
).Click the Delete button at the top of the page:
It takes a few moments to delete your instance.
Deauthorize Chrome Remote Desktop for the instance
If you no longer want to connect to the VM instance, you can disable it and remove the instance from the Remote Devices list.
- On your local computer, go to the Chrome Remote Desktop Remote Device list website.
- Click
crdhost
.
next to the instance
name - Click OK to confirm that the remote device connection should be disabled.
What's next
- Learn how to set up Chrome Remote Desktop on a Windows virtual machines.
- Learn about other options for creating a virtual workstation.
- Explore reference architectures, diagrams, and best practices about Google Cloud. Take a look at our Cloud Architecture Center.