SSH Keys#

Private SSH keys can be created that allow users to:

We have three SSH secret types for the above use cases: a generic ssh secret, git-ssh secret, or sftp-ssh secret. All three types mount your SSH private key as a file within your runs.

git-ssh and sftp-ssh are special commands that also set environment variables in addition to mounting SSH key files. Other than that, their configuration options are the same as a normal ssh key.

To see a full list of configuration options, you can run mcli create secret git-ssh --help or mcli create secret sftp-ssh --help.


Your SSH private keys must have no password as runs are non-interactive.

Introduction to SSH Secrets#

To create a simple SSH key:

mcli create secret ssh ~/.ssh/my_id_rsa

The above will store your private SSH key (given by the path ~/.ssh/my_id_rsa) in our secure secret manager, printing out the name under which it is stored. By default, the name will be the file stem (my_id_rsa in this case), but that can be customized with the --name argument.

mcli create secret ssh ~/.ssh/my_id_rsa --name my-ssh

By default, the ssh key will be mounted within your workload at /secrets/<secret-name>/secret. This mount path can be changed by supplying the --mount-path argument.

The mount path will also be stored under the environment variable SECRET_PATH_<UPPER_NAME> where <UPPER_NAME> is the secret name, all upper-case with β€œ-” replaced by β€œ_”.

For example, the following run YAML will show output of ls -l of the mounted ssh private key.

name: check-ssh
gpu_type: none
image: bash
command: |

Multiple clusters

Note, if you have access to multiple clusters, specify cluster: <cluster-name> to choose one to run the test on. All of your secrets are available across all of your clusters.

Running this with mcli run -f check-ssh.yaml yields:

> mcli run -f check-ssh.yaml

i  Run check-ssh-ms5i submitted. Waiting for it to start...
i  You can press Ctrl+C to quit and follow your run manually.
βœ”  Run check-ssh started
i  Following run logs. Press Ctrl+C to quit.

lrwxrwxrwx    1 root     root            13 Jun  8 00:17 /secrets/my-id-rsa/secret ->

Git SSH Secrets#

git-ssh secrets work exactly like regular ssh secrets as described above except adding a git-ssh secret also sets the GIT_SSH_COMMAND environment variable in your execution environment so that git will use your ssh key by default.

Creating a git-ssh secret is the same as a normal ssh secret:

mcli create secret git-ssh ~/.ssh/my_id_rsa

Adding an SSH Key to Github

To add the provided private key to Github, see the instructions here. Make sure your ssh key does not have a password or the git clone will fail in the execution environment.


Because the git-ssh secret creates an environment variable for you, only one such secret is allowed. If you need to have more, use the ssh secret type for the others instead.


Depending on your github repo’s security settings you may need to enable sso for your ssh key to work.

SFTP SSH Secrets#

sftp-ssh are the same as ssh secrets except the COMPOSER_SFTP_KEY_FILE environment variable will also set, which points to your key file. This allows using SFTP with Composer without needing to provide additional credentials in your code.

mcli create secret sftp-ssh ~/.ssh/my_id_rsa

Furthermore, adding an sftp-ssh secret also adds the host fingerprint of the SFTP server to a known_hosts file in the execution environment and sets the environment variable COMPOSER_SFTP_KNOWN_HOSTS_FILE pointing to that file path. This simplifies the setup for using SFTP servers.


Because the sftp-ssh secret creates a environment variables for you, only one such secret is allowed. If you need to have more, use the ssh secret type for the others instead.