This guide will help you to understand and use the Web Desktop and Web Shell on CyVerse's Atmosphere platform. They are both powered by Apache Guacamole.
The official Guacamole user guide can be found here, but please note that not all features will be available on Atmosphere.
CTRL + ALT + SHIFT to open a side menu. From here, you can browse system files and
The latest versions of the Chrome web browser support clipboard access. On your first time opening a connection to the Web Desktop or Web Shell, you will be prompted to grant clipboard permission. This will allow you to easily copy/paste directly into the Web Shell or Web Desktop.
At the time of writing this, the latest Firefox version is 65.0 and does not directly support clipboard access. If your version does not support it yet, you can enable the beta feature by visiting the URL
about:config and searching for
dom.events.testing.asyncClipboard. Setting the value of this feature to
true will enable clipboard use. However these are advanced settings so do this at your own risk.
If your browser does not support clipboard access, you can still copy/paste the old way:
In order to copy and paste between your local computer and your instance using our Web Desktop and Web Shell, you must use the text box in the side menu. The reason that you cannot directly copy/paste is that most browsers have strict control of clipboard access. A full explanation of this is available on the Apache Guacamole website.
- On Web Shell: text from your instance will be copied if you highlight it. Paste text into the terminal by right-clicking.
- On Web Desktop: use regular copy/paste methods:
CTRL+V, or right-click and find "Copy"/"Paste". Note that when using a Terminal within the Desktop, copy/paste commands change to
To upload a file, you can simply drag-and-drop it into the browser window. It will automatically be uploaded to your home directory.
To download files, pull up the side menu and double-click on the drive under "Devices". You can then navigate the filesystem by double-clicking through directories and then double-click on a file that you want to download.
You can also upload files by navigating through the filesystem in the menu and clicking the upload button.
Note: File upload can be pretty slow so it is recommended that you use a different method for files larger than 100 MB.
- Connect using the "Open Web Shell" button on the instance details page of Atmosphere.
- Uses SSH protocol with public key authentication to connect to your instance. The private keys are created and stored by Atmosphere and Guacamole.
When you close a Web Shell window, your shell session ends and is not preserved. You may wish to make your shell session persistent, so that you can disconnect from it and reconnect later. For this, we recommend using a terminal multiplexer, either
screen on your instance. Both of these may already be installed. Both can be used to keep your shell session active, and connect to it later, even if your browser disconnects.
Create a new terminal multiplexer session and activate it:
Now you can do your work inside terminal multiplexer, and your session will be preserved even if you get disconnected.
You can explicitly "detach" from your terminal multiplexer session by pressing
screen, followed by pressing the
d key – though this is not necessary when disconnecting Web Shell. You can just close the browser and your terminal multiplexer session will stay active.
When you re-connect to Web shell, you can re-attach to the first available terminal multiplexer session (i.e. the one that you opened earlier) with:
tmux a screen -x
This should bring you back to the same shell, exactly where you were earlier! It's possible to have more than one terminal multiplexer session open, and this may cause confusion. You can list all active terminal multiplexer sessions with:
tmux ls screen -ls
If you see multiple sessions listed, you can connect to a named session (e.g. session 0) with
tmux a -t 0 screen -x 0
For more information on using
tmux, please see
tmux documentation (e.g.
man tmux) and other articles on the web (e.g. A Gentle Introduction to
For more information on using
screen, please see
screen documentation (e.g.
man screen) and other articles on the web (e.g. GNU Screen on Arch Wiki).
- Connect using the "Open Web Desktop" button on the instance details page of Atmosphere.
- Uses VNC protocol.
Open a terminal and use these commands:
# Show the available resolution options xrandr -q # Change the resolution using the resolution or the corresponding number. xrandr -s <choice> # Example: xrandr -s 1920x1080 # or xrandr -s 6
This means that you were successfully authenticated by the Guacamole server, but it was unable to connect to your instance. This could be an issue with the instance, or perhaps with the server. If it continues to happen after a few tries, contact support. The most likely problem is the VNC server closed.
You can try to fix this yourself with these commands:
# Kill the Guacamole-specific VNC server # If you get an error, that means the server is already killed vncserver -kill :5 # Restart the VNC server vncserver -config ~/.vnc/config.guac :5
This means you are not authenticated for that connection. You have been authenticated by Guacamole but the instance you are trying to connect to is not your own. If you encounter this error, contact support.
This error occurs on SSH connections when the user mistypes the password or there is a key mismatch. If you still cannot connect after about 3 tries, contact support through Intercom so we can fix the SSH keys.