How Cloud Shell works

When you start Cloud Shell, it provisions a Google Compute Engine virtual machine running a Debian-based Linux operating system. Cloud Shell instances are provisioned on a per-user, per-session basis. The instance persists while your Cloud Shell session is active; after an hour of inactivity, your session terminates and its VM, discarded. For more on usage quotas, refer to the limitations guide.

With the default Cloud Shell experience, you are allocated with an ephemeral, pre-configured VM and the environment you work with is a Docker container running on that VM. You can also customize your environment automatically on VM boot to ensure that your Cloud Shell instance includes your preferred tools.

Persistent disk storage

Cloud Shell provisions 5 GB of free persistent disk storage mounted as your $HOME directory on the virtual machine instance. This storage is on a per-user basis and is available across projects. Unlike the instance itself, this storage does not time out on inactivity. All files you store in your home directory, including installed software, scripts and user configuration files like .bashrc and .vimrc, persist between sessions. Your $HOME directory is private to you and cannot be accessed by other users.

Authorization

When you make a Google Cloud API call or use a command-line tool that requires credentials (such as the gcloud command-line tool) with Cloud Shell for the first time, Cloud Shell prompts you with the 'Authorize Cloud Shell' dialog. Click 'Authorize' to allow the tool to use your credentials to make calls.

Refer to the Authorizing with Cloud Shell for more details.

Pre-configured environment variables

When Cloud Shell is started, the active project in Console is propagated to your gcloud configuration inside Cloud Shell for immediate use. GOOGLE_CLOUD_PROJECT, the environmental variable used by Application Default Credentials library support to define project ID, is also set to point to the active project in Console.

Zone selection

Cloud Shell is globally distributed across multiple Google Cloud Platform regions. When you first connect to Cloud Shell, you will be automatically assigned to the closest available geographical region. You cannot pick your own region and in the event that Cloud Shell does not pick the most optimal region, it will try to migrate your Cloud Shell VM to a closer region when it is not in use.

To view your current region, run the following command from a Cloud Shell session:

curl metadata/computeMetadata/v1/instance/zone

Image rollout

The Cloud Shell container image is updated weekly to ensure prepackaged tools are kept up to date. This means Cloud Shell always comes with the latest versions of Cloud SDK, Docker, and all its other utilities.

Root user

When you set up a Cloud Shell session, you get a regular Unix user account with a username based on your email address. With this access, you have full root privileges on your allocated VM and can even run sudo commands, if you need to.

Available tools

The Cloud Shell virtual machine instance has the following pre-installed tools:

Type Tool
Linux shell interpreters bash
sh
Linux utilities Standard Debian system utilities
Google SDKs and tools Google App Engine SDK
Google Cloud SDK including the gcloud command-line tool
gsutil for Cloud Storage
Text editors Emacs
Vim
Nano
Build and package tools Gradle
Helm
Make
Maven
Bazel
npm
nvm
pip
Composer
Source control tools Git
Mercurial
Additional tools Docker
iPython
MySQL client
gRPC compiler
TensorFlow

You can install additional software packages on the virtual machine instance but the installation will not persist after the instance terminates unless you install the software in your $HOME directory or create a custom environment.

Language support

The Cloud Shell virtual machine instance provides pre-installed language support for the following:

Language Version
Java JRE/JDK 1.8 and 1.11
Go 1.13
Python 2.7.13
Node.js v10.14.2
Ruby 2.6.0
PHP 7.0.33
.NET Core SDKs 2.0.0 and 2.1.502
Core runtimes 2.0.0 and 2.1.6

The default version of the Java environment is 1.11. To change the current Cloud Shell session to use version 1.8 of the JRE and JDK, enter the following at the Cloud Shell command prompt:

sudo update-java-alternatives -s java-1.8.0-openjdk-amd64 && export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

To change back to 1.11.0:

sudo update-java-alternatives -s java-1.11.0-openjdk-amd64 && export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64/jre

Safe mode

Cloud Shell will immediately close after connection if there is a problem in your .bashrc or .tmux.conf files. To resolve this, open Cloud Shell in safe mode by appending cloudshellsafemode=true to the URL. This will restart your Cloud Shell and log you in as root, allowing you to fix any issues in the files.

If you'd prefer to permanently delete all files in your home directory and restore your Cloud Shell home directory to a clean state, you can completely reset your Cloud Shell VM.