> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/use-artifact-registry/manage-registries/upstream-proxy.md). # Create an upstream proxy Learn how to configure your artifact registries with an upstream proxy. An **Upstream Proxy** in Harness Artifact Registry is a proxy configuration that allows your registry to automatically fetch and cache artifacts from external or remote registries. When a user requests an artifact that is not available locally, the registry directs the request to the configured upstream proxy, retrieves the artifact, and caches it for future use. {% hint style="info" %} **WHY USE AN UPSTREAM PROXY?** The upstream proxy is essential for caching open-source dependencies. During a build, if a required dependency is not already cached, it is retrieved from a public repository (for example, Docker Hub or Maven Central) and stored in your Upstream Proxy. This ensures continuous availability, even if the source repository experiences downtime. Harness caching reduces dependency on external services and safeguards access to critical artifacts. {% endhint %} ## Key benefits An upstream proxy provides these benefits: * **Caching:** Faster access to artifacts by storing them locally once fetched * **Centralization:** Consolidate external repositories into one location for easier management * **Access control:** Enforce your security policies while fetching artifacts * **Reliability:** Reduce dependency on external services by leveraging cached artifacts * **Automatic scanning:** Artifacts cached through upstream proxies are automatically scanned at ingest time via Supply Chain Security (SCS), not STO {% hint style="info" %} **VERIFY YOUR CACHE PATH CONFIGURATION** An incorrect cache path causes builds to bypass the cache entirely, resulting in significantly longer build times. If your builds are unexpectedly slow, verify the cache path in your upstream proxy settings matches your dependency manager configuration. {% endhint %} ## Create an upstream proxy {% tabs %} {% tab title="Interactive Guide" %} {% embed url="" %} Creating an Upstream Proxy in Harness Artifact Registry {% endembed %} {% endtab %} {% tab title="Step-by-step" %} To create an upstream proxy, perform the following steps: 1. On the **Registries** tab, select the dropdown next to **+ New Artifact Registry**, then select **Upstream Proxy**. 2. Select a [registry type](/artifact-registry/troubleshooting-and-resources/whats-supported.md#supported-registry-types). 3. Enter the **Upstream Proxy Key**.

ALLOWED CHARACTERS

The proxy key must start with a letter and can only contain lowercase alphanumerics, _, . and -.

4. Depending on the registry type, configure the source settings: 5. Choose your **Authentication** method.

PUBLIC VS PRIVATE AUTHENTICATION

Select an option based on your source:

6. Select **Create Upstream Proxy**. {% endtab %} {% endtabs %} {% hint style="info" %} **NPM bearer token** **Bearer token** authentication is available only for NPM upstream proxies. Go to [NPM](/artifact-registry/new-to-artifact-registry/quickstart/npm-quickstart.md#configure-an-upstream-proxy-optional) to configure a bearer token for an upstream proxy. {% endhint %} {% hint style="warning" %} **Harness Secret Manager required** Store your upstream registry authentication details in [Harness Secret Manager](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management/harness-secret-manager-overview). Harness Artifact Registry does not support external secret managers for upstream authentication. Harness Artifact Registry needs this setup to securely decrypt and validate credentials during authentication. {% endhint %} ## Metadata configuration The **Metadata configuration** setting on an upstream proxy allows you to configure how long, in seconds, the registry keeps cached metadata that it fetched from the remote source. Metadata includes package index information. When the time-to-live expires, the registry treats that metadata as stale and fetches it again. The upstream proxy exposes two cache TTL settings, **Metadata Cache TTL** and **Negative Cache TTL**. Both fields accept a value from 0 to 604,800 seconds (7 days). A value of 0 is treated as unset. Specify the values in seconds. The default is 10 minutes (600 seconds) to 30 minutes (1,800 seconds), depending on the package type of your upstream proxy. * **Metadata Cache TTL** (`metadataCacheTTL`): How long cached metadata, such as a package index, stays valid before the registry fetches it again. * **Negative Cache TTL** (`negativeCacheTTL`): How long the registry caches a not-found (`NOT_FOUND`) response. While that response is cached, the registry does not repeat the upstream lookup for an artifact it already failed to find. {% hint style="info" %} **SEPARATE FROM ARTIFACT CACHE EXPIRY** Metadata cache TTL controls how long package index metadata stays valid. The setting does not remove cached artifacts. Artifact cache expiry on the upstream proxy is a separate setting, and so are [lifecycle rules](/artifact-registry/use-artifact-registry/lifecycle-rules.md) for artifacts you publish. {% endhint %} ## Next steps Go to [Configure registries](/artifact-registry/use-artifact-registry/manage-registries/configure-registry.md) to set an upstream proxy for a registry. {% @harness-feedback/feedback %}