remote command group in Singularity allows you to login to
an account on the public container services cloud, or configure
Singularity to point to a local installation of Singularity
Enterprise, which provides an on-premise private Container Library,
Remote Builder and Key Store.
Users can setup and switch between multiple remote endpoints, which
are stored in their
file. Alternatively, remote endpoints can be set system-wide by an
remote command group configures Singularity to use
and authenticate to the public Sylabs Cloud, a private installation
of Singularity Enterprise, or community-developed services that are
remote command group cannot be used to e.g. configure
singularity to store credentials for access to a docker
registry. See the Support for Docker and OCI
guide for information about authenticating to various docker
Public Singularity Container Services¶
A fresh, default installation of Singularity is configured to connect
to the public cloud.sylabs.io
services. If you only want to use the public services you just need to
obtain an authentication token, and then
singularity remote login:
- Go to: https://cloud.sylabs.io/
- Click “Sign in to Sylabs” and follow the sign in steps.
- Click on your login id (same and updated button as the Sign in one).
- Select “Access Tokens” from the drop down menu.
- Enter a name for your new access token, such as “test token”
- Click the “Create a New Access Token” button.
- Click “Copy token to Clipboard” from the “New API Token” page.
singularity remote loginand paste the access token at the prompt.
Once your token is stored, you can check that you are able to connect
to the services with the
If you see any errors you may need to check if your system requires
proxy environment variables to be set, or if a firewall is blocking
*.sylabs.io. Talk to your system adminitrator.
You can interact with the public container services using various Singularity commands:
shub:// URIs with these commands
does not interact with the Sylabs Cloud.
Managing Remote Endpoints¶
Generally, users and administrators should manage remote endpoints
singularity remote command, and avoid editing
remote.yaml configuration files directly.
List and Login to Remotes¶
list existing remote endpoints, run this:
$ singularity remote list NAME URI GLOBAL [SylabsCloud] cloud.sylabs.io YES
[...] brackets around the name
SylabsCloud show that this
is the current default remote endpoint.
login to a remote, for the first time or if your token expires
or was revoked:
# Login to the default remote endpoint $ singularity remote login # Login to another remote endpoint $ singularity remote login <remote_name> # example... $ singularity remote login SylabsCloud singularity remote login SylabsCloud INFO: Authenticating with remote: SylabsCloud Generate an API Key at https://cloud.sylabs.io/auth/tokens, and paste here: API Key: INFO: API Key Verified!
Add & Remove Remotes¶
add a remote endpoint (for the current user only):
$ singularity remote add <remote_name> <remote_uri>
For example, if you have an installation of Singularity enterprise hosted at enterprise.example.com:
$ singularity remote add myremote https://enterprise.example.com INFO: Remote "myremote" added. INFO: Authenticating with remote: myremote Generate an API Key at https://enterprise.example.com/auth/tokens, and paste here: API Key:
You will be prompted to setup an API key as the remote is added. The web address needed to do this will always be given.
add a global remote endpoint (available to all users on the
system) an administrative user should run:
$ sudo singularity remote add --global <remote_name> <remote_uri> # example.. $ sudo singularity remote add --global company-remote https://enterprise.example.com [sudo] password for dave: INFO: Remote "company-remote" added. INFO: Global option detected. Will not automatically log into remote.
Global remote configurations can only be modified by the
root user and are stored in the
file, at the Singularity installation location.
remove an endpoint:
$ singularity remote remove <remote_name>
--global option as the root user to remove a global
$ sudo singularity remote remove --global <remote_name>
Set the Default Remote¶
A remote endpoint can be set as the default to use with commands such
pull etc. via
$ singularity remote use <remote_name>
The default remote shows up in
[...] square brackets in the output of
$ singularity remote list NAME URI GLOBAL [SylabsCloud] cloud.sylabs.io YES company-remote enterprise.example.com YES myremote enterprise.example.com NO $ singularity remote use myremote INFO: Remote "myremote" now in use. $ singularity remote list NAME URI GLOBAL SylabsCloud cloud.sylabs.io YES company-remote enterprise.example.com YES [myremote] enterprise.example.com NO
If you do not want to switch remote with
remote use you can:
pulluse an alternative library server with the
build --remoteuse an alternative remote builder with the
keysuse an alternative keyserver with the