Skip to main content
The trust contract is the safety boundary Gandalf enforces across scan, snapshot, diff, restore, and bundle flows. Every claim below is a runtime rule, not a suggestion.

​
What Gandalf does by default

  • Reads local user-global agent configuration only.
  • Does not execute MCP server commands, hooks, scripts, plugins, or agent tools discovered during a scan.
  • Does not use the network unless GANDALF_UPDATE_CHECK=1 is set.
  • Writes only to ~/.gandalf (or $GANDALF_STORE) for saves.
  • Changes supported user-global agent setup only through a reviewed, provider-backed action or an explicit restore --apply --experimental.
  • Omits raw secrets from evidence and does not manage project .env values.
  • Does not follow symlinks on write targets.
  • Requires explicit --apply and --experimental (or GANDALF_EXPERIMENTAL=1) before restoring content.
  • Creates rollback paths for restore operations where the evidence kind supports it.
  • Reports missing local tools and env keys without installing packages or restoring secret values.

​
Path confinement

All restore and bundle writes are confined to the declared home and project roots. Confinement is checked in plan parsing, apply, rollback, and bundle import. Callers must supply roots, or the operation fails closed. The path that is actually written must be the same path that was validated. Symlink write targets are refused rather than resolved.

​
Review Changes before mutation

Every mutating flow shows Review Changes first:
  • Restore-backed applies compare a baseline snapshot to current evidence and list writable items, unsupported items with reasons, risk metadata, and rollback instructions.
  • Provider-backed setup actions preview the target, expected effect, and execution mechanism before running.
  • Marketplace-originated Review Actions stay non-mutating unless a concrete provider can preview and execute the effect.
Review is not apply authority. Mutating flows refresh or revalidate the underlying plan at apply time so the action still matches what you reviewed.

​
Unsupported items stay observe-only

Evidence kinds without dedicated apply handlers are not force-fitted into generic file replacement. They surface in inventory and diffs but are marked unsupported for mutation with a concrete reason.

​
Experimental gating

Destructive operations require an explicit opt-in:
  • restore --apply requires --experimental or GANDALF_EXPERIMENTAL=1.
  • bundle import --apply-content requires --experimental.
  • bundle import with sensitive prefixes should be previewed with --dry-run or --quarantine first.

​
Update checks

Update notices are off by default. Set GANDALF_UPDATE_CHECK=1 to enable them. See Environment variables.