Getting started with the Verily Workbench Web UI

Getting started with the Verily Workbench Web UI.


The Verily Workbench web UI is accessed at

Any operations you do using the terra command-line utility will be reflected in the Web UI, and vice versa.


Workspaces are where researchers and teams connect and organize all the elements of their research. This includes data, code, analysis, documentation, and collaboration with others. Workspaces are also a way for data & tool providers to deliver data and tools to researchers, along with helpful resources such as documentation, code, and examples.

Listing your workspaces

Click on “Workspaces” in the left nav bar to list your workspaces. You will see workspaces that were shared with you, as well as workspaces that you created.

Creating a new workspace

Click on the New workspace button to create a new workspace.

Creating a new workspace.

Enter a name for the workspace, then in the next page, you can optionally add a description.

Add an optional description to a new workspace.

Once the workspace creation has completed, you’ll see a page with your workspace details:

New workspace details.

Sharing or duplicating a workspace

You can share workspaces with others, or duplicate them. You can do this via the buttons at the top right of a workspace page, or via the ’three-dot’ menu to the right of a listed workspace.

Sharing a workspace

To share a workspace, you add the people and groups you want to share with, and indicate the permissions you’re giving them.

Duplicating, or cloning, a workspace

Duplication of a workspace will create a copy of the workspace, including controlled and referenced resources, that you can then modify (see below for more information). Notebook instances are not cloned.

(This is the same as terra workspace clone via the command-line tool.)

Deleting a workspace

You can also delete a workspace via the same menus, as shown in the screenshots above.

Workspace Resources

Resources comprise a variety of entities whose chief purpose is to facilitate analysis. In many cases resources are simply multimodal data that can be managed within the workspace, but they aren’t limited to data exclusively. Inside a workspace, the “Resources” tab is where the data resources associated with that project are found.

Referenced vs workspace-controlled resources

Referenced resources, or simply references, represent data and other elements in Verily Workbench by pointing to a source that exists outside of the current workspace. While references are functionally identical to their source, they afford more flexibility and less risk, as anything done to a reference has no effect on its source.

An example of a reference is a BigQuery dataset you want to work with in Workbench. By creating a reference, you can bring that dataset into the workspace as a reference, and perform analysis and workflows using that referenced resource. You can safely delete the reference, or make new references in other workspaces, with no effect on the original dataset. There are no limits to the number of references you can create, as long as access to the source is maintained.

Controlled resources are cloud resources that are managed or created by Verily Workbench within the current workspace, such as a Cloud Storage bucket that was made using your workspace. If you wanted to use the same bucket in a different workspace, a reference to the original controlled resource would need to be created in the other workspace. In other words, a controlled resource is its own source, and native to the Workbench workspace it exists within. If the workspace or the resource is deleted, it no longer exists.

Creating a controlled resource

A workspace-controlled resource is a GCS bucket or a BigQuery dataset.

Creating a referenced resource

A referenced resource can point to a GCS bucket or object; or a BigQuery dataset or table.

Data catalog

The data catalog is an integrated tool within Verily Workbench that streamlines the process of data discovery. Browse data collections curated by stewards, with powerful filters to minimize the amount of time taken to discover data relevant to your study. Export entire or partial collections to your Workbench workspace for use in interactive analysis or workflows. Easy version tracking and optioned updates ensure all collaborators can stay in sync.

Data collections are diverse datasets, available from Verily Workbench’s data catalog for use as referenced data in your own workspace. Collections are curated by data stewards that ensure data quality, reproducibility, and associated lineage. Many collections will have policies attached that determine how the data may be accessed and used. Collections you have access to may be entirely or partially referenced for use in your Workbench workspace.


Folders let you organize your workspace’s resources.

Workspace Cloud Environments

A cloud environment is a configurable pool of cloud computing resources. Cloud environments consist of a virtual machine and a persistent disk, with some useful libraries and tools preinstalled. They’re ideal for interactive analysis and data visualization, and can be finely tuned to suit analysis needs.

Cost is incurred while the cloud environment is running, based on your configuration. You can pause the environment when it’s not in use, but there’s still a charge for maintaining your disk.

See Using Cloud Environments for Analysis(/docs/how_to_guides/using_cloud_environments/) for information on creating and using cloud environments.

Workspace Git repositories

You can add references to git repos from your workspace. When you add a reference to a git repository to your workspace, it will then be cloned to any cloud environment that you subsequently create in that workspace.

With public repos, use the https:// syntax for the repo URI. This will allow the repo to be cloned without an SSH key set up.

With private repos, use the git@ syntax for the repo URI. This is required for Workbench to succesfully clone the repo. For a clone of a private repo to be successful, the Workbench key must be set up as described below.

Creating an SSH key

For private repos, you will need an SSH key to access the repo from your workspace. Workbench makes this straightforward by generating and managing an SSH key for you. Visit your Profile in the Web UI (upper-right corner) to view your public SSH key, which you can copy and regenerate.

You must associate the new SSH public key with your GitHub account using this process. See this page for more detail.

Last Modified: 16 November 2023