IBM Cloud Docs
Working in Cloud Shell

Working in Cloud Shell

IBM® Cloud Shell contains a personal workspace and sessions where you can run commands. You can open up to five concurrent sessions, which operate independently so you can work with different resources, regions, and accounts at once.

To open Cloud Shell, click the IBM Cloud Shell icon IBM Cloud Shell icon in the IBM Cloud console. A session starts and automatically logs you in to the IBM Cloud CLI with your current account.

Your Cloud Shell workspace

Each time that you open Cloud Shell, you connect to your Cloud Shell workspace. A workspace is a dedicated environment that holds your user and session data and provides temporary storage for you to work with files. Workspaces are separate for each user, account, and region, which each run in their own virtual machine. This means that only you can access your workspace, and if you're a user in multiple accounts, you have separate workspaces for each account, which keeps your data isolated and secure. For more information about storing data in Cloud Shell, see Temporary workspace storage.

Deleting your Cloud Shell workspace

Deleting your Cloud Shell workspace ends and deletes all sessions in the workspace. All files and data within the workspace are erased. Before you delete the workspace, download any files that you want to keep.

To delete your Cloud Shell workspace, complete the following steps:

  1. Download any files that you want to keep.
  2. From your Cloud Shell workspace, click the Actions icon Actions icon, and then select Delete.
  3. In the confirmation window, click Delete. A blank page is displayed.
  4. Click the Add icon Add icon to open a new Cloud Shell session. This action also creates a new Cloud Shell workspace.

Working with sessions

A Cloud Shell session is the terminal interface where you can run commands, scripts, and other tools. It's similar to the command prompt on your local machine, but it's preconfigured with the full IBM Cloud CLI and numerous plug-ins and tools so that you can work in IBM Cloud without having to install anything. For more information about the CLI, see Getting started with the IBM Cloud CLI.

When you open a session, you start in your Cloud Shell workspace's home directory, /home/<user-name>. Your home directory provides a temporary place for you to work with files in Cloud Shell. It is shared between all of your sessions. Because data in your home directory isn't persisted, any files that you add or change are removed after two hours of inactivity. For more information about your Cloud Shell workspace and home directory, see Working with files.

A diagram that shows the workspace storage, which can be accessed in your home directory. The five sessions connect to the same workspace storage.
Figure 1. Your personal workspace and sessions in Cloud Shell

Opening sessions

To open a new session, click the Open icon Open a new session icon. You can have up to five sessions open at one time. Each session maintains separate command histories, which are removed when you close the session. Because the workspace storage is shared between sessions, you can save a file to your home directory in one session, and then open the file in another session.

Each session automatically closes if it's not used for an hour. If you don't use Cloud Shell for two hours - that is, another hour after the last session is closed - all files and data in your Cloud Shell workspace are erased. If you need to step away from Cloud Shell, be sure to download any files that you want to keep. For more information, see Working with files.

Switching accounts

When you open a session, you're logged in with the IBM Cloud CLI targeting the account and region that you were in when you opened Cloud Shell. This account and region are the default for every session.

To switch the default account for your sessions, close Cloud Shell, switch to a different account in the IBM Cloud console menu bar, and then reopen Cloud Shell.

Because you have separate workspaces for each account, your session history and temporary file storage are also separate. This means that when you switch accounts, you see different session tabs and don't have access to any files that you were working with in the previous account.

Changing locations

The Tokyo region for Cloud Shell is deprecated and will no longer be supported by Cloud Shell as of 2 July 2024. For more information, see the release notes.

Cloud Shell runs in the Dallas (us-south), Frankfurt (eu-de), and Tokyo (jp-tok) regions. Each Cloud Shell location operates independently, which means that your workspace storage, sessions, and usage are separate. When you work in Cloud Shell, the location that you're in determines the following aspects:

  • Where your workspace data is stored, including any files that you upload and your user data, such as your session history and usage quota
  • The default region that's targeted by the IBM Cloud CLI: us-south, eu-de, or jp-tok

By default, the location that's closest to you geographically is selected when you open Cloud Shell from the console. For example, if you're in California then Cloud Shell opens to the Dallas region, but if you're in Paris it opens to the Frankfurt region.

To change to Cloud Shell in a different location, find the current location in the Cloud Shell menu bar, and click Change. Select the location that you want to switch to, and click OK.

If you change from the default location, Cloud Shell remembers your location preferences by saving them as cookies in your browser. If you switch to a different browser, clear your browser cookies, or your cookie preferences don't allow personalization cookies, Cloud Shell will open in the default location.

Restarting Cloud Shell

When you restart Cloud Shell, any open sessions are closed and all of your files and data are removed. Before you restart, be sure that you download any files that you want to keep to your local system.

To restart, click the Menu icon More icon, and select Restart.

Tracking your usage

You can use Cloud Shell for up to 50 hours within a week per region. Any time that you have at least one open session counts toward this usage quota, even if you aren't actively running commands. For example, if you're working in Cloud Shell for 15 minutes and then leave your session open for a 30-minute lunch break, those 45 minutes are counted as usage. If you have three sessions open at the same time over an hour period, your usage is one hour because concurrent sessions don't count as additional usage. To minimize your usage, be sure to close sessions after you're done using them.

If you use all of your quota, your Cloud Shell sessions are closed. Closing Cloud Shell removes any data in your workspace, including your files and command history.

When you reach your usage quota, you get a notification that Cloud Shell will close in 5 minutes. Use this time to complete any urgent tasks.

At any point, you can track your usage and check when your weekly quota resets. In the Cloud Shell menu bar, click the Menu icon More icon, and select Usage quota. You can view how many hours you used Cloud Shell during the current weekly period and the day and time when it resets.

The time that you used of the 50-hour usage quota resets back to 0 at the same time each week. Even after you used all of your quota, you can still use IBM Cloud Shell for up to 5 minutes at a time to complete quick tasks, such as to run a few simple commands.

IBM Cloud Shell is intended for IBM Cloud administration and development purposes. Any usage outside of these guidelines might result in your access to IBM Cloud Shell or IBM Cloud being suspended. Because Cloud Shell is intended for interactive purposes only, long-running processes are stopped. For more information, see the IBM Cloud Terms and Notices.