pmg/docs/sandbox-presets.md

Sandbox Presets

A preset is a named bundle of sandbox allowances for one workload. For example: what lint-staged needs from git, or what astro dev needs to write and bind. Any tool with a known sandbox footprint can have a preset. Presets are additive-only: they grant allowances on top of your sandbox profile and can never remove a deny rule. A profile-authored deny always beats a preset allowance, and preset validation rejects paths that would opt out of PMG's mandatory protections (.git/hooks, .git/config writes, credential files). The two opt-outs a preset can perform, both visible in its YAML: read access to .git/config (required for git to operate) and un-scrubbing specific built-in credential variables by exact name.

Using presets

Discover what's available:

pmg sandbox preset list
pmg sandbox preset list --label dev-server --author SafeDep

Inspect a preset before trusting it. The output is the preset's own YAML, including its threat notes describing the residual risk of each allowance:

pmg sandbox preset show git

Apply presets to the current repository (run from the project root; this saves into the per-repo overlay used by every future PMG run there):

pmg sandbox allow preset=git preset=astro

Or attach presets permanently to a custom sandbox profile:

# ~/.config/safedep/pmg/sandbox/profiles/pnpm-custom.yml
name: pnpm-custom
inherits: pnpm
package_managers: [pnpm]
presets: [git, astro]

Presets are applied by reference: upgrading PMG (or editing a user preset) updates the allowances everywhere the preset is used.

Available official presets

Preset	For
git	lint-staged, husky, turbo, changesets
astro	Astro dev server and build
vite	Vite dev server and build
nextjs	Next.js dev server and build

Creating your own preset

Scaffold, edit and validate:

pmg sandbox preset init myapp --author "Your Name" --label myapp
pmg sandbox preset edit myapp     # opens $VISUAL / $EDITOR, validates on save
pmg sandbox allow preset=myapp    # apply to the current repo

User presets live in <config-dir>/sandbox/presets/ (e.g. ~/.config/safedep/pmg/sandbox/presets/ on Linux) — community presets are installed by dropping a file there. pmg sandbox preset list always shows where a preset came from: builtin (embedded in the pmg binary, maintainer-reviewed) vs the user file path, and a user preset that reuses a built-in name is marked SHADOWED — the built-in always wins, so an official preset cannot be silently replaced. A preset file looks like:

kind: preset
name: myapp
description: What this preset enables, one line
metadata:
  author: Your Name
  labels: [myapp, dev-server]
# Threat notes: explain what each allowance permits and why it is acceptable.
filesystem:
  allow_write:
    - ${CWD}/.myapp/**
network:
  allow_bind:
    - localhost:8080

Validate it:

pmg sandbox preset lint ./myapp.yml

Rules the schema enforces:

• Allow-only sections: filesystem.allow_read/allow_write, process.allow_exec, network.allow_bind, environment.allow. Deny rules and profile booleans are rejected.
• Paths must be anchored at ${CWD}/, ${HOME}/ or ${TMPDIR}/, no .., and must not name sensitive files (.env, .ssh, ...).
• Binds must be loopback (localhost, 127.0.0.1, ::1).
• environment.allow entries are exact variable names, no globs.
• No network.allow_outbound: current sandbox drivers cannot enforce host-granular outbound rules (a single allow means blanket network access), so presets are not allowed to change outbound posture at all.

Precedence guarantees, in addition to PMG's mandatory denies:

• A preset environment allowance covered by a profile-authored environment.deny pattern is dropped with a warning. Surviving preset allowances still opt out of PMG's built-in credential variable scrubbing, which is their intended use.
• A preset filesystem allowance never removes a deny rule authored in a profile: deny wins over allow on every platform.
• The git preset allows reading .git/config and writing under .git/, but writes to .git/config and everything under .git/hooks stay blocked by mandatory denies on all platforms.

A preset name that collides with an official preset is shadowed — the official one always wins. To propose an official preset, open a pull request adding it under sandbox/presets/ with threat notes and tests.