> 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/add-and-prioritise-upstream-proxies.md).

# Add and prioritize upstream proxies

Attach one or more upstream proxies to a registry and set the order in which they are consulted when an artifact is not found locally.

After creating an upstream proxy, you attach it to one or more registries. When a client requests an artifact that is not stored locally, Harness queries the attached proxies in the order you define until one returns the artifact.

You can attach upstream proxies of matching format or, when the feature flag is enabled, other Harness registries of the same type.

## Before you begin

* The upstream proxy must already exist before you can attach it to a registry. Go to [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md) to create one.
* Your role must include **Create/Edit** permission on the registry. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) for details.

## Add upstream proxies to a registry

1. In the navigation menu, select **Registries**.
2. Click the registry you want to configure.
3. Select the **Configuration** tab.
4. In the **Upstream proxy** section, click the edit icon to open the **Configure and prioritize upstream proxy** drawer.
5. In the **Select upstream proxy** picker, search for and select the proxies you want to attach. You can select multiple proxies.
6. Click **Apply**.
7. In the **Selected proxies** list, drag the rows to set the lookup order.
8. Save the setting.

Harness queries proxies from top to bottom. The first proxy that has the requested artifact serves the response and Harness caches it locally.

## Prioritize proxies

The order of proxies matters. When a client requests an artifact, Harness checks the local registry first. If the artifact is not found, it queries the upstream proxies from the top of the list downward.

Place the proxy most likely to have your artifacts at the top to minimize latency and unnecessary upstream requests.

{% hint style="warning" %}
**Avoid publishing the same artifact locally and to an upstream proxy**

When a registry receives a request, it checks the local store first. A locally published version shadows any newer version available in an upstream proxy; the proxy is never queried if the artifact exists locally. Do not publish the same package to both a local registry and an upstream proxy that caches the same scope.
{% endhint %}

## Add another Harness registry as an upstream source

You can aggregate multiple Harness registries into a single access point by adding a Harness registry as an upstream source. This is useful when you want to serve artifacts from several project-level registries through one account-level entry point.

{% hint style="info" %}
**Feature flag required**

Adding a Harness registry as an upstream source requires the `HAR_SUPPORT_LOCAL_REGISTRY_AS_UPSTREAM_PROXY` feature flag. Contact [Harness Support](mailto:support@harness.io) to enable it.
{% endhint %}

When adding a Harness registry as an upstream source, the registry must have no upstream proxies configured within it.

## Remove an upstream proxy

1. Open the registry's **Configuration** tab.
2. In the **Upstream proxy** section, open the edit drawer.
3. Deselect the proxy you want to remove and click **Apply**.
4. Save the setting.

Removing a proxy does not delete the proxy itself; it only detaches it from this registry. Existing cached artifacts in the proxy remain available until removed by a lifecycle rule or manually deleted.

## Troubleshooting

<details>

<summary>The proxy I want to attach does not appear in the picker</summary>

The picker shows only proxies that match the package type of the registry. Confirm the proxy was created with the correct package type. If it was recently created, try refreshing the page.

</details>

<details>

<summary>Artifacts are still being fetched from the public registry instead of the proxy cache</summary>

Check that your client tooling (for example, `.npmrc`, `pip.conf`, or `settings.xml`) is configured to use the Harness registry URL. If the client is not routing through Harness, it will bypass the proxy and fetch directly from the public source.

Also verify that the proxy appears in the **Selected proxies** list, not only the **Available upstream proxies** list.

</details>

<details>

<summary>A newer version is available upstream but the old version is served</summary>

Harness returns the locally cached version when one exists. If the upstream has a newer version, the local cache must be cleared. Delete the specific cached version from the upstream proxy registry, then pull again. Harness fetches the latest from the upstream source and re-caches it.

</details>

## Next steps

* [Dependency Firewall overview](https://developer.harness.io/artifact-registry/3.0/dependency-firewall/overview.md): apply security policies to artifacts fetched through proxies
* [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md)
* [Lifecycle management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md): automate cleanup of cached artifacts

{% @harness-feedback/feedback %}
