PyPI

The proxy implements the PyPI simple-index protocol, so any client that speaks it can install through ShieldedStack.

Endpoint: <proxy-url>/pip/

Authentication: the API key, sent as the password in HTTP basic auth. The username is not checked; _ is the conventional placeholder.

Configuration below is written for pip. Other clients that speak the same protocol, such as uv, Poetry, and Pipenv, use the same endpoint and the same key through whatever index-URL and credential settings they expose.

pip

The index URL carries the credential, so the shape is the same everywhere pip accepts one:

https://_:YOUR_API_KEY_HERE@<proxy-host>/pip/

On the command line:

pip install --index-url https://_:YOUR_API_KEY_HERE@<proxy-host>/pip/ package-name

This puts a secret in your shell history. It is fine for a one-off check and wrong as a habit.

In a configuration file, which is the better default. On Linux and macOS that is ~/.config/pip/pip.conf, on Windows %APPDATA%\pip\pip.ini:

[global]
index-url = https://_:YOUR_API_KEY_HERE@<proxy-host>/pip/

Against an HTTP-only deployment, pip also needs the host marked as trusted:

[global]
index-url = http://_:YOUR_API_KEY_HERE@<proxy-host-and-port>/pip/
trusted-host = <proxy-host>

trusted-host turns off TLS certificate verification for that host. Use it only for an HTTP-only deployment, or temporarily while an internal certificate is being trusted properly.

Committing the configuration

Because the credential lives inside the index URL, a pip.conf with a real key must never be committed. Commit a template instead, as pip.conf.template:

[global]
index-url = https://_:${SHIELDEDSTACK_API_KEY}@<proxy-host>/pip/

Add pip.conf and pip.ini to .gitignore, and generate the real file from the template:

mkdir -p ~/.config/pip
envsubst < pip.conf.template > ~/.config/pip/pip.conf

In CI, where no file needs to persist, pass the flag instead:

pip install --index-url https://_:$SHIELDEDSTACK_API_KEY@<proxy-host>/pip/ -r requirements.txt

Verify

pip install requests

The installed package appears under Packages in the Control Plane, attributed to the project name on the API key.

Troubleshooting

401 or 403. Check the credential is embedded in the index URL in the https://_:KEY@host/pip/ form, and that the key has not expired.

Certificate errors. Add trusted-host = <proxy-host> for an HTTP-only deployment or an internal certificate pip does not trust yet, or pass --trusted-host <proxy-host> for a single command.

Configuration seems ignored. pip reads from several locations depending on platform and virtualenv. Confirm the file you edited is the one in effect, and prefer --index-url on the command line to isolate the problem.