Select and manage private mirrors

Private mirrors give an account a protected path to public or authenticated package sources. They are read-only and support PyPI, npm, and Maven. The CLI uses rvs art mirror commands to manage them. Each mirror is backed by a remote cache, whose stable ID is used when connecting it to a private repository.

Ravenstash keeps two source types distinct:

Type	Target	Example
Official	Ravenstash-curated source	mirror:pypiorg
Custom	Source defined by your account	custom-mirror:piwheels

Official mirrors are available on every plan. Creating a custom mirror requires an eligible paid plan and organization administrator access where applicable.

The prefixes prevent a mirror from being mistaken for a private repository. No namespace name is reserved.

Use an enabled official mirror

Select an official source by its one-word slug:

rvs art mirror select pypiorg
rvs art install requests

Common official defaults are pypiorg, npmjs, and maven-central. When the matching mirror is already enabled for the selected account, install helpers can use it without a saved target. You do not need to redeclare the source for every operation.

Add an official mirror to the active account when it is not yet available:

rvs art mirror add pypiorg --select

Create and select a custom mirror

Create a custom HTTPS source:

rvs art mirror create-custom piwheels \
  --kind pypi \
  --api-url https://www.piwheels.org/simple/ \
  --publication-control externally-controlled \
  --select

For a protected source, pass the secret through an environment variable rather than the command line:

export UPSTREAM_TOKEN="${TOKEN_FROM_SECRET_STORE}"
rvs art mirror create-custom company-python \
  --kind pypi \
  --api-url https://packages.example.com/simple/ \
  --publication-control user-controlled \
  --auth-scheme bearer \
  --secret-env UPSTREAM_TOKEN \
  --allowed-host packages.example.com \
  --select

Basic authentication also accepts --username with --secret-env. Use --artifact-url when package files are served from a different HTTPS origin and repeat --allowed-host for each approved download host.

Select an existing custom mirror with:

rvs art mirror select --custom company-python

If the same custom name exists in more than one registry kind, add --kind.

Use a mirror

Select the mirror, then use normal rvs package commands:

rvs art mirror select pypiorg
rvs pip install requests

rvs art mirror select --custom company-python
rvs pip install internal-sdk

When several accounts are available, use the intended account before selecting its mirror:

rvs account use org:acme
rvs art mirror select pypiorg
rvs pip install requests

Use a mirror directly or through a repository

Select a mirror directly when a build only needs packages from that source. Connect a mirror to a private repository when one repository should provide both private packages and approved public dependencies:

rvs art mirror list --kind pypi
rvs art repo upstream add packages pypi \
  --remote-cache REMOTE_ID \
  --min-age-hours 3
rvs art select platform/packages

Age controls hold back brand-new releases for the configured period, reducing exposure during the riskiest first hours after publication. Set the appropriate minimum age for each direct mirror and private-repository connection.

Inspect and manage mirrors

rvs art mirror list
rvs art mirror list --kind npm
rvs art mirror show CACHE_ID
rvs art mirror set-age CACHE_ID --min-age-hours 3
rvs art mirror current

Clear only the active target:

rvs art mirror clear

Delete a mirror after disconnecting private repositories that use it:

rvs art mirror delete CACHE_ID

Publishing is private-repository only

A mirror cannot accept package publishing. If a mirror is selected, publish commands stop before invoking the native client and ask for a private repository target:

rvs art select platform/releases
rvs twine upload dist/*