> ## Documentation Index
> Fetch the complete documentation index at: https://docs.root.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> All configuration options for Root registry authentication, proxy settings, and CI/CD environment variables.

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:**

```bash theme={null}
# 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](/getting-started/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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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):

```groovy theme={null}
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.