Configuration Reference

This page documents all configuration options for connecting to Root’s registries, including authentication, network settings, and recommended CI/CD variable names.

Registry Configuration

Root exposes two registries:

Registry	URL	Purpose
Root Image Catalog	`cr.root.io`	Container images (Docker/OCI)
Root Library Catalog	`pkg.root.io`	Application packages (Python, JavaScript, Java, Go)

Per-ecosystem package registry URLs:

Ecosystem	Registry URL
Python (pip/uv/Poetry)	`https://pkg.root.io/pypi/simple/`
JavaScript (npm/pnpm/Yarn)	`https://pkg.root.io/npm/`
Java (Maven)	`https://pkg.root.io/maven/`
Go (Go modules)	`https://pkg.root.io/gobinary`

Per-ecosystem configuration file locations:

Ecosystem	Config File
Docker	`~/.docker/config.json`
pip	`~/.netrc` or `pip.conf`
npm	`.npmrc` (project or global)
Maven	`~/.m2/settings.xml`
Gradle	`~/.gradle/gradle.properties`
Poetry	`pyproject.toml` or `poetry.toml`
uv	`~/.netrc` or `uv.toml`
Yarn	`.yarnrc.yml`
pnpm	`.npmrc`
Go	`GOPROXY` environment variable

Authentication Configuration

Token format: Root tokens are opaque strings used as passwords. There is no specific prefix or format requirement for registry tokens. API keys use the prefix apik_. Token scopes: A single Root token provides access to both cr.root.io and pkg.root.io. There are no separate per-registry tokens. Per-registry credential configuration:

# Docker
docker login cr.root.io --username rootio --password $ROOT_TOKEN

# npm
npm config set //pkg.root.io/npm/:_authToken $ROOT_TOKEN

# Maven (settings.xml)
# Use ${env.ROOT_TOKEN} to read from environment

See Authentication for per-ecosystem setup instructions.

Environment Variables

The following environment variables are recognized by the Root CLI and registry integrations: Root uses two different tokens for two different purposes:

Token	Purpose	Where to get it
Registry token (`ROOT_TOKEN`)	Authenticates to `cr.root.io` and `pkg.root.io` registries	Root platform onboarding
API key (`ROOTIO_API_KEY`)	Authenticates the `rootio_patcher` CLI to the Root API	Settings → Token Management → Generate API Token

These are separate credentials. You need both if you use both the registries and the patcher CLI.

Variable	Description	Default
`ROOT_TOKEN`	Registry token - used by Docker, pip, npm, Maven, etc. to pull from Root’s registries	-
`ROOTIO_API_KEY`	API key for `rootio_patcher` CLI and the Root API	-
`ROOTIO_API_TOKEN`	Alternative name for the API key (used by the rootio-remediation-action)	-
`ROOTIO_API_URL`	Override for the Root API endpoint	`https://api.root.io`
`ROOT_API_URL`	Override for the Root API base URL (v1 path)	`https://api.root.io/v1`
`ROOT_IMAGE_REGISTRY`	Override for the image registry URL	`cr.root.io`
`ROOT_PKG_REGISTRY`	Override for the package registry URL	`pkg.root.io`

Proxy and Network Settings

Root’s registries support standard HTTP proxy configuration:

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

Docker respects these environment variables for registry pulls. Set them before running docker pull or in Docker’s daemon configuration:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:8080",
      "httpsProxy": "http://proxy.example.com:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

TLS / custom certificates: If your organization uses a TLS intercepting proxy or a private CA, configure Docker to trust your CA certificate:

# Place your CA cert in the Docker certs directory
sudo mkdir -p /etc/docker/certs.d/cr.root.io
sudo cp your-ca.crt /etc/docker/certs.d/cr.root.io/ca.crt

CI/CD Variable Reference

Recommended secret names for common CI/CD systems: GitHub Actions (store in Repository or Organization Secrets):

Secret Name	Value
`ROOT_TOKEN`	Your Root registry token (for `cr.root.io` / `pkg.root.io`)
`ROOTIO_API_KEY`	Your Root API key (for `rootio_patcher` CLI)
`ROOTIO_API_TOKEN`	Alternative name for API key (for `rootio-remediation-action`)

Usage:

env:
  ROOT_TOKEN: ${{ secrets.ROOT_TOKEN }}
  ROOTIO_API_KEY: ${{ secrets.ROOTIO_API_KEY }}

GitLab CI (store in Project or Group CI/CD Variables, masked):

Variable Name	Value
`ROOT_TOKEN`	Your Root registry token
`ROOTIO_API_KEY`	Your Root API key (for patcher)

Usage:

before_script:
  - echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin

CircleCI (store in Project Environment Variables):

Variable Name	Value
`ROOT_TOKEN`	Your Root registry token

Jenkins (store as a Secret Text credential):

withCredentials([string(credentialsId: 'root-token', variable: 'ROOT_TOKEN')]) {
  sh 'echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin'
}

HashiCorp Vault: Store your Root token at a path like secret/root/token and retrieve it via Vault’s CI/CD integrations.

Documentation Index

​Registry Configuration

​Authentication Configuration

​Environment Variables

​Proxy and Network Settings

​CI/CD Variable Reference

Registry Configuration

Authentication Configuration

Environment Variables

Proxy and Network Settings

CI/CD Variable Reference