Quickstart

This page configures a single package manager to install through Upwarden. Pick your ecosystem; the wire shape is the same for every ecosystem — the proxy speaks each registry’s native protocol, so the install commands and lockfile shapes are unchanged from a direct-to-registry install.

Prerequisites

You have:

• A project API key (vk_...) minted under your tenant. If you don’t, ask your Upwarden admin — or see Installation to stand up your own instance and Create your first key to mint one.
• The proxy hostname for your ecosystem. The default convention is <eco>.pkg.<your-domain> (for example npm.pkg.upwarden.io for the Upwarden-hosted instance).

npm / Bun / pnpm / Yarn

.npmrc

registry=https://npm.pkg.upwarden.io/
//npm.pkg.upwarden.io/:_authToken=${VG_NPM_API_KEY}

Then install as normal:

npm install lodash@4.17.21

A successful install through Upwarden reads identically to a direct npm install. To confirm you’re going through the proxy: npm config get registry.

PyPI (pip, uv)

# pip does NOT expand ${VAR} inside pip.conf — config files and environment
# variables are separate mechanisms there, so a ${...} written into pip.conf is
# sent literally and the install fails. Use the environment variable, which the
# shell expands, or paste the key into pip.conf in full.
export PIP_INDEX_URL=https://${VG_PYPI_API_KEY}@pypi.pkg.upwarden.io/simple/

pip install requests==2.31.0

crates.io (Cargo)

~/.cargo/config.toml

[source.crates-io]
replace-with = "upwarden"

[registries.upwarden]
index = "sparse+https://crates.pkg.upwarden.io/index/"

# NOT `token = "${VG_CRATES_API_KEY}"` in config.toml — cargo does not expand
# ${VAR} there, so the literal string would be sent as the credential. Supply it
# as an environment variable instead; the NAME is derived from the registry name
# above, so renaming the registry changes the variable with it — uppercased,
# with hyphens turned into underscores (my-reg -> CARGO_REGISTRIES_MY_REG_TOKEN).
export CARGO_REGISTRIES_UPWARDEN_TOKEN=${VG_CRATES_API_KEY}

Note

config.json is served anonymously on purpose — cargo reads it before authenticating, to discover whether auth is required. A mistyped token therefore bootstraps fine and 401s on the first real fetch: the registry is up, the credential is wrong.

Sparse index only. cargo publish is not proxied.

RubyGems

bundle config --global https://rubygems.pkg.upwarden.io \
  "${VG_RUBYGEMS_API_KEY}:x"

# Gemfile
source "https://rubygems.pkg.upwarden.io" do
  gem "rake", "13.0.6"
end

NuGet (.NET)

<!-- NuGet.Config -->
<configuration>
  <packageSources>
    <add key="upwarden"
         value="https://nuget.pkg.upwarden.io/v3/index.json"
         protocolVersion="3" />
  </packageSources>
  <packageSourceCredentials>
    <upwarden>
      <add key="Username" value="ci" />
      <add key="ClearTextPassword" value="${VG_NUGET_API_KEY}" />
    </upwarden>
  </packageSourceCredentials>
</configuration>

Maven Central

settings.xml

<mirror>
  <id>upwarden</id>
  <url>https://maven.pkg.upwarden.io/maven2</url>
  <mirrorOf>central</mirrorOf>
</mirror>
<server>
  <id>upwarden</id>
  <username>ci</username>
  <password>${env.VG_MAVEN_API_KEY}</password>
</server>

Go modules

export GOPROXY="https://go.pkg.upwarden.io,direct"

The bearer rides in the Authorization: Bearer ${VG_GO_API_KEY} header via a ~/.netrc entry or a Git URL rewrite.

What happens behind the scenes

Each install request hits the proxy, which authenticates the bearer to a tenant + project, runs Upwarden’s verdict pipeline against the requested artefact, fetches it from the upstream registry on the SAFE path, and streams the bytes back. BLOCKED and QUARANTINED verdicts surface as a policy-shaped error response that the package manager’s normal install flow already knows how to print.

See Concepts → tenants, projects, keys for the model your CI integrates with.