Skip to content

Logging into BRC Clusters

New in 2026: Users can use SSH Certifications for password-less login and VS Code remote

As of January 2026, users are now able to use an SSH certificate to log into Savio. After logging in an initial time, SSH certificates allows users to log in directly without a password, reducing the number of times you would need to enter a PIN+OTP. The certificates also allow users to forward ports from applications running on Savio and enable remote editing of files and code execution with certain IDEs, such as with VS Code using the Remote-SSH extension. For more information, see below!

Unlike most remote computer systems that you may have encountered to date, when logging into the BRC clusters (via SSH), you'll need to enter a password that changes each time you log in. You'll generate (create) these passwords - known as One Time Passwords (OTP) - using the Google Authenticator application on your smartphone or tablet. Requiring time-expiring, one-time-use passwords helps protect your work and data from unauthorized access - and potential damage or alteration - by intruders. Moreover, it helps protect the cluster itself from attacks, so that it can remain highly available to the campus community.

Looking to access Savio without the terminal?

If you would like avoid using SSH via the terminal for logging into and using Savio or would prefer a web-based interface, check out our Open OnDemand (OOD) service. There, you will instead use single sign-on authentication via your Calnet ID for logging in. The OOD service provides standard shell access, alongside a variety of applications for interactivate computing such as Jupyter Lab and RStudio.

Setting up one-time password authentication

Setting up your mobile device to generate these one-time passwords, so you can log into the BRC clusters, is fairly straightforward. It typically takes between 10 and 30 minutes, and you only need to do it once. Please follow these instructions.

Logging into BRC Clusters

1. Make sure that the Google Authenticator app is running on your smartphone or tablet. (You’ll need to enter a one-time password displayed by this app at step 3, below.)

2. On your laptop, desktop, or other device running a terminal/SSH program, connect to the cluster via SSH; e.g.:

ssh yourusername@hpc.brc.berkeley.edu

(Be sure to substitute your actual username for the placeholder yourusername in the example above.)

3. At the Password: prompt, enter the token PIN, followed immediately, without spaces, by the 6-digit one-time password currently displayed by the Google Authenticator app on your smartphone or tablet; e.g.:

Password: PIN_hereOTP_here

For instance, if your PIN was 9999 (hint: don’t use this example as your own PIN!), and the one time-password currently displayed by Google Authenticator was 123456, you’d enter the following at the Password: prompt:

Password: 9999123456

Please note that no characters will appear on the screen in the password prompt when you enter in the digits.

Troubleshooting log in issues

If you've already set up your token but are unable to log in successfully - here's what to try:

1. Make sure you're including the PIN as part of your password

At the Password: prompt, make sure that you're entering your token PIN, followed immediately by the 6-digit one-time password from Google Authenticator. (There should be no spaces or punctuation between the token PIN and the one-time password.)

2. Wait to enter the one-time password until a new one has just been displayed

If the 'countdown clock' indicator in the Google Authenticator app is nearing its end, signifying that the existing password is about to expire, try waiting until a new one-time password has been displayed. Then enter that new password, immediately after your PIN, at the Password: prompt.

3. Check that, in your SSH command or in the configuration for your SSH application, you're using your correct login name (i.e., your Linux user name) on the cluster

In particular, make sure that you're not inadvertently using the name of one of your SLURM scheduler accounts (which typically begin with fc_ for Faculty Computing Allowance users or co_ for Condo partners), in place of your login name.

4. Check that, in your SSH command or in the configuration for your SSH application, you're using the correct hostname for the cluster's front-end/login nodes, hpc.brc.berkeley.edu, or for its Data Transfer Node, dtn.brc.berkeley.edu.

5. Test - and if needed, reset - your token or its PIN

  • Visit the Non-LBL Token Management web page.
  • Log in to this Token Management page, by clicking the button for the relevant external account (University of California, Berkeley [i.e., your CalNet ID], Facebook, Google, or LinkedIn) that you used when you set up your token, and then following the onscreen directions.
  • A list of one or more tokens should then be displayed. From this list, find your relevant token: the one that you entered into Google Authenticator on the smartphone or tablet you're currently using. (If you want to check this further, the "TOTP number" that appears in the box for your token, on the Token Management web page, should match the TOTP number in Google Authenticator's window on your device. On some small devices, you might need to press/click and hold on the token's entry to see the TOTP number, and perhaps even pivot the device to landscape mode to read the full number.)
    • If there's only a "Reset" option in your relevant token's box, click that link. Then proceed to the next step, below.
    • If there's a "Test" option in the token's box, click that link, then enter your PIN followed immediately by your Google Authenticator 6-digit one-time password, and click the "Test Now" button.
    • If your test(s) fail, click "Done". Then click the "Reset PIN" link and reset your PIN. (You can even 'reset' it to your current PIN.)
    • Try the "Test" option once again. In the token's box, click the "Test" link, then enter your PIN followed immediately by your Google Authenticator 6-digit one-time password, and click the "Test Now" button.
    • Once you get a successful test of your PIN plus one-time password on this web page, you can try logging into the cluster once again and see if you're successful there, as well.
    • If the "Test" option keeps failing, check the time on the device where you are generating the one-time-passwords. Make sure the time on the device is in sync with the network time.

6. Try creating a brand new token and add the new token to Google Authenticator, as described in the instructions above. (Before or after doing this, you can delete your existing token - both on the LBL Token Management web page and in the Google Authenticator app on your device - to avoid any confusion with the new token.)

7. If none of the above tips give you a clue on what is not working, try to SSH to BRC resources from a different IP address i.e from a different computer or laptop. If that works email the IP address from where its not working to BRC support @ brc-hpc-help@berkeley.edu.

Using SSH certificates to log in to Savio (and use VS Code Remote-SSH)

As of January 2026, users are now able to use an SSH certificate to log into Savio. After logging in an initial time, SSH certificates allows users to log in directly without a password, reducing the number of times you would need to enter a PIN+OTP. An SSH Certificate Authority issues signed SSH keys with a specified validity period. You will then receive an SSH key triplet consisting of a public key, a signed public key, and a private key, and the certificate is automatically set to expire after the designated time period, or after 12 hours if no duration is specified. You or an administrator can revoke the certificate at any time. Script and instructions to request SSH certificates are given below.

For users looking to utilize VS Code on Savio via the Remote-SSH extension, you will need to follow both the basic installation instructions as well as the more advanced SSH configuration set up below. This set up will additionally allow you to use any application built on top of VS Code that allows use of the Remote-SSH extension, including Cursor (an AI-assisted IDE) and Positron (a data-science centric IDE for use with Python and R).

Installing the certification script

The SSH certification script is provided by LBNL's HPCS team, who help run and administer the Savio computing cluster. To get started, clone their lrc-scripts repository, which includes the request-cert.sh and revoke-key.sh scripts.

git clone https://github.com/lbnl-science-it/lrc-scripts.git

Then run request_cert.sh to create a certificate in your $HOME/.ssh/ssh_certs directory with the name brc_cert.

cd lrc-scripts
./request_cert.sh -p brc

When prompted, enter your Savio username, PIN and (on a separate line) OTP to generate the certificate and then use the ssh command as shown below to login. Help options for the script can be listed with the --help flag, i.e., by running ./request_cert.sh --help

You will have to recreate the certificate after the time limit (12 hours by default) has passed.

Updating your SSH config to use the certification identity

For ease of use, you can further update your SSH config to automatically utilize the created certification. This is especially useful for users who are interested in using the Remote-SSH VS Code extension to connect to Savio. To do so, add the following lines to your ssh config file (typically located at ~/.ssh/config), filling in your username where specified. You may need to create this file if it does not yet exist (e.g., via touch ~/.ssh/config).

Host savio
    User <username>
    HostName hpc.brc.berkeley.edu
    IdentityFile ~/.ssh/ssh_certs/brc_cert

These changes should reflect immediately after updating your SSH config. With these updates, after requesting an SSH certificate with the request_cert.sh script, you should be able to log into Savio simply by running ssh savio. If using VS Code with the Remote-SSH extension, savio should show up as an available target in your list of remote hosts. Alternatively, you can use the Command Palette (usually opened with the shortcuts F1 or CTRL-SHIFT-P) to run the Remote-SSH: Connect to Host... command, which should list savio as a configured host.

Warning

When logging on to Savio with VS Code and the above SSH configuration, your VS Code session will be running on a login node. As always when using Savio, please avoid running expensive computations on login nodes.

Installing and running the certification script on Windows

While Windows now has a built-in terminal, it does not typically have a bash shell or some common Linux utilities installed by default , which you will need to be able to run the request_cert.sh script. There are several ways around this, but we'll walk primarily through one method, using the Windows subsystem for Linux.

The Windows Subsystem for Linux (WSL) is a utility that can install a Linux distribution to use directly from your Windows operating system and will have all of the necessary shell utilities. The installed Linux subsystem operates like a virtual machine, and can be actively used side-by-side with your Windows installation. We note, however, that the WSL filesystem differs than the primary filesystem -- they can both be accessed from either side, but have different paths -- and so the steps to generate and use a certificate are a bit more involved.

For example, if using WSL with an Ubuntu distribution (the default installation), we can begin the installation process by opening Powershell (directly, or within the Termina application), and simply running the ubuntu command. This will launch you into a shell that is running Ubuntu, and put you into the home directory of the Linux subsystem (/home/<username>). From here, you can install the LRC scripts repository and run the request_cert.sh -p brc as described above. This will generate the the certification script in /home/<username>/.ssh/ssh_certs/ in the WSL filesystem.

To use the default system SSH from the Windows side (such as with Putty), you should need to specify the identity file with the path as:

IdentityFile //wsl$/Ubuntu/home/<username>/.ssh/ssh_certs/brc_cert

If using WSL, we recommend specifying the path in this way so that any applications running on the Windows side, such as VS Code, can access the SSH config and needed files correctly. Alternatively, if you are only using SSH for terminal access, you could follow the instructions above as-written and use SSH from within the spawned ubuntu shell itself, which would utilize the WSL copy of SSH and access the config file located at /home/<username>/.ssh/config.

Logging in to compute nodes with running jobs

If you have a running job on a compute node, with some additional modifications to your SSH configuration you can also use your certification to log in directly to the compute node itself (including with VS Code Remote-SSH)! You can log into any compute node which is currently allocated to you (viewable with squeue -u <username>), no matter how the resources were allocated (via sbatch, srun, salloc, or even OpenOnDemand).

Using salloc with the --no-shell flag is a good way to start such a job without also starting a shell that, if closed, would cancel the job.

Suppose you have allocated a node to use for computing on savio4_htc with the following command:

salloc -A <account> -p savio4_htc --qos=savio_normal -t 00:10:00 --no-shell

When the job is allocated you will be shown information about which node has been allocated to you, e.g. n0108.savio4. If the full hostname is not shown, you can always use the command squeue -u <username> to get the list of nodes which are currently allocated for your use. To be able to SSH directly into the compute node, you can additionally modify your SSH config with the following lines:

Host savio
    LogLevel QUIET
    User <username>
    HostName hpc.brc.berkeley.edu
    IdentityFile ~/.ssh/ssh_certs/brc_cert
    ForwardAgent yes
    IdentitiesOnly yes

Host n????.savio?
    LogLevel QUIET
    User <username>
    StrictHostKeyChecking no
    ProxyJump savio
    HostName %h

Continuing this example, you should be able to log in to your allocated compute node (n0108.savio4) with the command ssh n0108.savio4. With VS Code, you will need to use the Command Palette to run the Remote-SSH: Connect to Host... command to log in to the allocated node. In this use case, the certificate is only used to achieve the "proxy jump": when logging onto a compute node, you will be prompted to enter your PIN+OTP.

Keeping a consistent editor session on compute nodes with VS Code

When using the above configuration, with n????.savio? specified as the host for compute nodes, VS Code will maintain a separate editor history for each and every host you log in to. If you would like to keep the editor state consistent across different sessions when using VS Code on the compute nodes, you can use an alternative SSH configuration as below, which would require you to edit the HostName entry every time.

Host savio-compute
    LogLevel QUIET
    StrictHostKeyChecking no
    ProxyJump savio
    HostName <exact_hostname_change_everytime>
    User <username>

Without such a modification, by default, VS Code will keep separate editor histories for each node and re-prompt you to confirm the operating system of each host and any workspace trust preferences each time you log in to a new compute node.