Hi, we’ve written some custom nextflow plugins for our company use, and we would like to make them available from a private plugin registry. We have an artifact repository we generally publish the plugins to, but it obviously does not include the plugin index file.
The NXF_PLUGINS_REGISTRY_URL envvar seems to imagine that people will want to do this, but I couldn’t find any instructions. The Gradle plugin appears to interact with some API that manages it. Is there any official guidance for how to setup a private registry?
Great question. I had the same question myself, and there are a few approaches depending on your setup.
Current options for private plugins
The most practical approach today is to use the NXF_PLUGINS_TEST_REPOSITORY environment variable, pointing it to a JSON index file you host and control (local path or remote URL). The JSON follows the same format as the public plugin registry, so you can manage your own versioning. Despite the name implying it’s for testing, this is the recommended approach for running private plugins in production without publishing publicly.
There’s an important caveat though: Nextflow’s plugin downloader uses Java’s standard HTTP client, which only supports basic auth (credentials embedded in URLs). It does not support token-based auth headers, which rules out GitHub’s native API for binary downloads. Here are the patterns that work today:
Private S3 bucket with IP/VPC restrictions: If you run on AWS Batch or from predictable IPs, restrict the bucket by policy rather than credentials. The URLs are plain HTTPS, nothing to manage. Cleanest option.
CloudFront in front of private S3: Add a CloudFront Function for basic auth if your compute IPs vary. Credentials need to be embedded in both the NXF_PLUGINS_TEST_REPOSITORY URL and the url fields inside your JSON index.
Any HTTP server with basic auth: Nexus, Artifactory, or similar artifact servers work the same way, with the same caveat about credentials needing to be in every URL.
Alternatively, NXF_PLUGINS_DIR can point to a local directory of pre-installed plugins, but this requires a POSIX path and works better in on-prem environments than cloud.
What’s coming
A proper self-hosted private plugin registry is on the roadmap, which will include more mature authentication support beyond basic auth. If you have specific auth requirements (OAuth, GitHub tokens, etc.), I’d encourage you to share them here - the team is actively gathering input to shape that work.