# Upstream proxy

## What Is an Upstream Proxy?

An upstream proxy is a registry that fetches packages from an external source on demand and serves them to your builds. Think of it as a trusted middleman between your developers and public registries such as npm, PyPI or Maven Central.

## How an Upstream Proxy Works

| Step   | What happens                                                                 |
|--------|------------------------------------------------------------------------------|
| Request| A build asks the proxy for a package                                         |
| Lookup | The proxy checks its local store, then configured upstream sources in priority order|
| Fetch  | If the package is missing, the proxy retrieves it from the upstream source    |
| Serve  | The package is returned to the client, and may be cached for later requests    |

## Why Upstream Proxies Matter

Routing dependencies through one point brings several benefits:

- Builds keep working during public registry outages
- Packages removed upstream stay available
- One place to see what teams consume
- A point to apply security and license checks

Visibility and control come from the same change.

## Proxying vs Caching

**Proxying** passes each request through to the upstream source. **Caching** stores a copy so later requests are served locally. Most proxies do both, and caching is what protects builds when the source goes down.

## Final Thought

An upstream proxy turns public registries from a direct dependency into a managed one. It makes external packages predictable.

## Frequently Asked Questions

### Is an upstream proxy the same as a mirror?

Not quite. A mirror copies an entire source in advance, while a proxy fetches only the packages that are requested.

### Does an upstream proxy make dependencies safe?

No. It centralizes access, but safety depends on the scanning and policy checks applied to what it serves.

### Can an upstream proxy cause stale packages?

It can if cached metadata is not refreshed. Most proxies let you set how long cached data is trusted.

### Which package formats can be proxied?

Common examples include npm, Python, Maven, Go, NuGet and container images. Support varies by tool.

### What happens when two upstreams have the same package?

The proxy follows a configured priority order, so the higher-priority source wins.