> 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/3.0/registries/create-an-upstream-proxy.md).

# Create an upstream proxy

Create an upstream proxy to cache artifacts from an external registry such as Docker Hub, Amazon ECR, or a private server on demand.

An upstream proxy is a special registry configuration that fetches artifacts from an external source on demand and caches them locally. When a client requests an artifact that is not already in the cache, Harness retrieves it from the configured upstream source, stores it, and serves future requests from the local copy.

An upstream proxy lets you:

* Cache open-source dependencies so builds continue even if the upstream source is down or rate-limiting requests.
* Route all external artifact traffic through a single controlled access point.
* Apply Dependency Firewall policies to artifacts fetched from public registries.

Artifacts cached through an upstream proxy are automatically scanned at ingest time when the Harness Supply Chain Security module is enabled.

## Before you begin

* Your role must include **Create/Edit** permission on Artifact Registry. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) for details.
* If the upstream source requires authentication, store the credentials in [Harness Secret Manager](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management/harness-secret-manager-overview) before you create the proxy. Harness Artifacts does not support external secret managers for upstream authentication.

## Create an upstream proxy

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select the **Registry type** that matches the upstream source format.
7. Enter an **Upstream Proxy Key**.

   The key must start with a letter and can only contain lowercase letters, numbers, underscores (`_`), hyphens (`-`), and periods (`.`).
8. Configure the **Source** for the upstream:

   | Source option | When to use                                                                        |
   | ------------- | ---------------------------------------------------------------------------------- |
   | Docker Hub    | Public Docker Hub registry                                                         |
   | AWS ECR       | Amazon Elastic Container Registry                                                  |
   | Custom        | Any other registry, including on-premises servers (for example, JFrog Artifactory) |

   When you select **Custom**, enter the **Remote registry URL**. The URL must start with `https://`. Use the base URL of the repository, not a specific artifact path.
9. Set the **Authentication** method:

   * **Anonymous**: for public sources that do not require credentials.
   * **Username and Password**: for private sources. Select the Harness secrets that store your credentials.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>NPM bearer token</strong></p><p>Bearer token authentication is available only for npm upstream proxies. Go to the <a href="https://developer.harness.io/artifact-registry/3.0/setup/npm.md">npm client setup page</a> to configure a bearer token for an npm upstream proxy.</p></div>
10. Select **Create upstream proxy**.

After creation, attach the proxy to one or more registries so clients can use it. Go to [Add and prioritize upstream proxies](https://developer.harness.io/artifact-registry/3.0/registries/add-and-prioritise-upstream-proxies.md).

## Configure metadata cache TTL

After creating the proxy, you can configure how long the proxy caches package metadata fetched from the upstream source.

Open the upstream proxy, select **Configuration**, then find the **Metadata configuration** section.

| Field                                 | What it controls                                                                            | Range                      | Default              |
| ------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------- | -------------------- |
| **Metadata Cache Time to Live (TTL)** | How long cached package index metadata stays valid before Harness checks the upstream again | 0–604,800 seconds (7 days) | 600 seconds (10 min) |
| **Negative Cache TTL**                | How long Harness caches a not-found response before retrying the upstream                   | 0–604,800 seconds (7 days) | 600 seconds (10 min) |

A value of 0 means the field is unset and the default applies.

{% hint style="info" %}
Metadata cache TTL controls how long package index metadata stays valid. It does not remove cached artifacts. To remove cached artifacts on a schedule, go to [Lifecycle management](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).
{% endhint %}

## Delete cached artifacts

Deleting a cached artifact removes it from the local cache only. It does not appear in the **Deleted** view. Pull the artifact again through the proxy to re-cache it from the upstream source.

## Troubleshooting

<details>

<summary>Can I use an on-premises JFrog Artifactory as an upstream source?</summary>

Yes, if Harness can reach your Artifactory server over HTTPS. Select **Custom** as the source, enter the Artifactory repository URL (starting with `https://`), and choose **Username and Password** authentication. Store the credentials as Harness secrets before creating the proxy.

To copy artifacts from Artifactory in bulk rather than fetching on demand, go to [Migrate artifacts](https://developer.harness.io/artifact-registry/3.0/get-started/migrate-to-harness-artifacts/from-jfrog-artifactory.md).

</details>

<details>

<summary>Can I pre-fill the cache before clients request artifacts?</summary>

No. An upstream proxy fetches and caches an artifact the first time a client requests it. To fill the cache in advance, request the artifact through the proxy once, for example in a pipeline step that installs or pulls the dependency.

</details>

<details>

<summary>My build times are unexpectedly slow after setting up an upstream proxy</summary>

Verify that your dependency manager is configured to use the proxy registry URL (for example, in `.npmrc`, `pip.conf`, or `settings.xml`). If the client is still resolving packages directly from the public registry, it is bypassing the cache entirely.

</details>

## Next steps

* [Add and prioritize upstream proxies](https://developer.harness.io/artifact-registry/3.0/registries/add-and-prioritise-upstream-proxies.md) to attach the proxy to a registry.
* [Dependency Firewall overview](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/overview.md) to apply security policies to cached artifacts.

{% @harness-feedback/feedback %}
