pmg/docs/system-install.md

System Install (Linux)

Use system install when one machine or image should protect every user account: shared VMs, golden Docker images, and similar setups.

sudo pmg setup install --system

Requires Linux and root. To uninstall:

sudo pmg setup remove --system
sudo pmg setup remove --system --config-file   # also remove the system config file

Per-user pmg setup install remains available and does not conflict with a system install. The PMG executable used during setup must be executable by every user. Install PMG under a system path such as /usr/local/bin.

Files created

Item	Path
Configuration	/etc/safedep/pmg/config.yml
Package-manager shims	/usr/local/lib/pmg/bin
Shell PATH snippet	/etc/profile.d/pmg.sh

Making shims visible on PATH

System install writes shims to /usr/local/lib/pmg/bin. Processes only use them when that directory is on PATH ahead of the real npm, pip, and other package managers.

Linux VMs and login shells

pmg setup install --system installs /etc/profile.d/pmg.sh, which prepends the shim directory for login shells.

sudo pmg setup install --system

New login sessions pick this up automatically. For an already open shell, start a new login session or run:

source /etc/profile.d/pmg.sh

Confirm with:

which npm    # should resolve under /usr/local/lib/pmg/bin
pmg setup doctor

Docker and container images

Docker RUN does not load /etc/profile.d. After system install you must set ENV PATH so build steps and the runtime container see the shims:

FROM node:22-bookworm

RUN curl -fsSL https://raw.githubusercontent.com/safedep/pmg/main/install.sh | sh \
 && pmg setup install --system

# Required: profile.d is not sourced during docker build
ENV PATH="/usr/local/lib/pmg/bin:$PATH"

# Optional: switch user; PATH from ENV still applies
RUN mkdir -p /app && chown node:node /app
WORKDIR /app
USER node
COPY --chown=node:node package*.json ./
RUN npm ci

Derived images inherit that ENV. Later RUN npm install / RUN pip install go through PMG for any USER.

If a child Dockerfile sets ENV PATH=... again, keep /usr/local/lib/pmg/bin ahead of the real npm/pip directories. Leaving it out (or behind those toolchains) drops interception.

PMG running on the Docker host cannot inspect package installations inside docker build. PMG must be installed in the image as shown above.

Configuration

The system config file is authoritative for every user. A per-user config.yml is ignored while /etc/safedep/pmg/config.yml exists.

pmg config set and pmg config edit fail under a system config. Update the file as root, or redeploy it through your image or configuration management.

Optional lockdown (global_lockdown: true) is documented in config.md.

Limitations

• Virtualenv. After source .venv/bin/activate, bare pip uses the venv binary and skips PMG shims. Call pmg pip … explicitly.
• Version managers. Tools like nvm, pyenv, volta, and asdf often prepend their own bin directories from shell rc files that run after /etc/profile.d. That can put real npm/pip ahead of PMG shims even when the shim directory is on PATH. Prefer putting /usr/local/lib/pmg/bin first in a durable ENV PATH / login PATH, or call pmg npm / pmg pip explicitly. pmg setup doctor warns for any supported package manager that resolves outside the shim directory.
• No shell aliases. System install only installs PATH shims. There is no ~/.pmg.rc alias layer.
• Config changes. pmg config set and pmg config edit are unavailable while the system config is active. Edit /etc/safedep/pmg/config.yml as root, or redeploy the file.
• Custom sandbox policy_templates. Relative paths in the system config resolve under each user's config directory, not /etc/safedep/pmg. Prefer absolute paths.
• pmg sandbox allow. Blocked when the system config sets global_lockdown: true.

User data directories

Shared policy lives under /etc/safedep/pmg. Runtime data stays per user:

Data	Default location
Event logs	~/.config/safedep/pmg/logs/
Cloud sync state	~/.config/safedep/pmg/cloud-sync.db
Cache	~/.cache/safedep/pmg/
Sandbox overlays	~/.config/safedep/pmg/sandbox/overlays/
Persistent CA keypair	~/.config/safedep/pmg/ca-cert.pem, ca-key.pem

You can relocate these with PMG_CONFIG_DIR and PMG_CACHE_DIR.

The invoking user must be able to write their config directory. If they cannot, PMG skips event logging for that run (and prints a warning) and continues the package-manager command. Cloud sync also needs that directory to store pending events.

In Docker images, avoid creating /home/<user>/.config/safedep as root during the build. Either fix ownership for the runtime user, or set PMG_CONFIG_DIR to a writable location.

For cloud sync, enable cloud in the system config and provide credentials (SAFEDEP_API_KEY and SAFEDEP_TENANT_ID, or a keychain login on developer machines).

Certificates

System install does not set up a MITM certificate authority. For npm and pip on Linux, PMG's default ephemeral CA and environment-variable injection are enough.

To install a persistent CA into the OS trust store, use a separate command:

pmg setup cert install --system

Run that as your normal user. Details are in cert.md.