Text of docs.cloud.google.com › shell › docs › how-cloud-shell-works as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

How Cloud Shell works | Google Cloud Documentation

Skip to main content Console English Deutsch Español Español – América Latina Français Indonesia Italiano Português Português – Brasil עברית 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in Cloud Shell Start free Home Documentation Application development Cloud Shell Stay organized with collections Save and categorize content based on your preferences. How Cloud Shell works Cloud Shell lets you manage Google Cloud resources and develop applications directly from your browser without installing local tools.

When you start a session, Cloud Shell provisions an ephemeral Compute Engine virtual machine running Debian-based Linux. Because Google Cloud owns and manages this virtual machine, it does not appear within your Google Cloud projects. Google Cloud provisions Cloud Shell instances 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 is 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 can't be accessed by other users. When using Cloud Shell, you cannot expand persistent disk storage space.

For more control of your storage persistence, and for more storage space, you can use Cloud Workstations . Cloud Shell also offers Ephemeral mode which is the Cloud Shell experience without persistent disk storage. With Ephemeral mode, you'll have faster startup times but all the files you create in your session are lost on session end. Authorization When you make a Google Cloud API call or use a command-line tool that requires credentials (such as the Google Cloud CLI) with Cloud Shell for the first time, Cloud Shell prompts you to authorize.

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 the Google Cloud 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 the project ID, is also set to point to the active project in the Google Cloud console.

The environment variable WEB_HOST points to the hostname of your Cloud Shell VM which you can use to make HTTPS requests to the environment. Zone selection Cloud Shell is globally distributed across multiple Google Cloud regions. When you first connect to Cloud Shell, you are automatically assigned to the closest available region. You can't pick your own region and if Cloud Shell doesn't pick the closest region, Cloud Shell tries to migrate your Cloud Shell VM to a closer region when your Cloud Shell VM isn't 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 keep prepackaged tools up to date. This means Cloud Shell always comes with the latest versions of the gcloud CLI, Docker, and 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 gcloud CLI and tools Google Cloud CLI including the gcloud CLI Text editors Emacs Vim Nano Build and package tools Gradle Helm Make Maven Bazel npm nvm pip uv 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 17 (OpenJDK) Go Latest Python 3.12 Node.js LTS Ruby 3.2 PHP 8.3 .NET Core SDKs 6.0, 7.0, and 8.0 The default version of the Java environment is 17. To change the current Cloud Shell session to use version 1.11 of the JRE and JDK, enter the following at the Cloud Shell command prompt: sudo update-java-alternatives -s java-1.11.0-openjdk-amd64 && export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 To change to 21: sudo update-java-alternatives -s java-1.21.0-openjdk-amd64 && export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 To change back to 17: sudo update-java-alternatives -s java-1.17.0-openjdk-amd64 && export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/jre Safe mode If there's a problem in your .bashrc or .tmux.conf files, Cloud Shell immediately closes after connection.

Safe mode restarts your Cloud Shell instance and logs you in as root, allowing you to fix any issues in the files. To open Cloud Shell in safe mode: Append cloudshellsafemode=true to the URL. In Cloud Shell, click more_vert , click Safe Mode , and then click Restart . To permanently delete all files in your home directory and restore your Cloud Shell home directory to a clean state, you can reset your Cloud Shell VM .

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates. Last updated 2026-11-10 UTC.