Technician Mode

Config

Configuration is stored in pinman_config.json in the app data directory (the active project home: pinman/data/hub/projects/<name>/ for dev/test, C:\ProgramData\Pinman\projects\<name>\ for prod). Each project home has its own config file.

Settings are read and written via:

  • CLI: pinman config get <key> / pinman config set <key> <value>
  • UI: the Config page (gear icon)

Managed settings#

A few settings are managed — they are bound to data outside the config file, so changing the value alone would orphan what it points at. config set and the Config page refuse them, and name the command that changes them safely instead. Today that is backups_root (owned by pinman capture move).


Mode#

How much authority this machine grants, and to whom.

What Pinman may change on this machine. See What Pinman will and won't change.

machine_readonly#

Type: boolean | Default: true | Restart: pinman service restart api

When on, applying, undoing or running a profile only previews: nothing is written to the machine. Allow a single action with Disable read-only for this action or --allow-writes. A Machine read-only chip in the top bar shows it is on. After pinman config set, restart the API (pinman service restart api).

profile_restricted#

Type: boolean | Default: false | Restart: pinman service restart api

This guard works only while Machine read-only is also on; when either setting is off, Profile Scripts run full Python. When active, it refuses scripts outside Pinman's approved language before any of that source runs. A technician can allow full Python for one exact script version. Restricted mode is a guardrail, not a sandbox. After pinman config set, restart the API (pinman service restart api).

operator_mode_enabled#

Type: boolean | Default: false | Restart: pinman service restart

Offer the operator interface on this machine. Turning this off makes it technician-only. Operator mode also needs the operator kit — without it this setting has no effect.

operator_readonly#

Type: boolean | Default: false | Restart: pinman service restart api

When on, the operator Controls page cannot change anything. There is no per-action override. After pinman config set, restart the API (pinman service restart api).

require_savepoint#

Type: boolean | Default: false | Restart: pinman service restart api

Pinman changes a setting in a file only when a Savepoint holds that file as it is now; otherwise it asks you to take one or overwrite anyway.


Backups#

Where and how this machine stores backups.

backups_root#

Type: path | Default: "backups" | Managed by: pinman capture move --to <path>

The directory where pinman stores all backups — a folder name inside the project home (the default, backups) or an absolute path. Set during pinman project create; changed afterwards with pinman capture move --to <FULLPATH>, which relocates the archived files and rewrites the stored capture paths before updating this value. This is a managed setting — pinman config set backups_root ... is refused.

backup_interval#

Type: integer (min) | Default: 30

How often (in minutes) the auto-backup scheduler runs.

backup_workers#

Type: integer | Default: 1

Number of parallel threads used for file copies during a backup operation. 1 means serial (safe, slower).

The best value depends on the drives being copied from and to. When the source and the backups folder are on different drives, use the lower of the two: HDD 2, SSD 4, NVMe 8, USB 1, network share 6. When both are on the same physical drive, use HDD 1, SSD 2, NVMe 4, USB 1. pinman capture maint workers --auto checks the drives and sets it for you.

backup_capacity_low_multiplier#

Type: float | Default: 3.0

Threshold multiplier for low-disk-space warnings. If free space is less than N × full-backup-size, the capacity is classified as low.

busy_processes#

Type: list of strings | Default: []

Process names that indicate the machine is "in use". Backup and other disruptive operations may be suppressed or warned when these are running.


Directories#

Working folders (relative to the app data folder, or absolute).

reference_dir#

Type: path | Default: "reference"

Path to the reference data directory (static lookup files such as property catalogs and blacklists). Relative paths are resolved from the app data directory.

profiles_dir#

Type: path | Default: "profiles"

Path to the directory containing profile YAML files. Relative paths are resolved from the app data directory.

extract_dir#

Type: path | Default: "extract"

Directory under app data where extracted .reg and .json files (winreg/winrt exports) are cached.


Scanning#

How Pinman walks the filesystem and detects changes.

directory_exclude_match#

Type: list of strings | Default: []

Names to skip in every directory scan on this machine, so each schema does not have to exclude the same clutter — version-control folders, caches, logs. Each pattern is matched against a file or folder name (not its path), with * and ? wildcards; a matching entry is not scanned or captured. Example: [".git", "*.log", "Cache", "crash.*"].

The schema wins: an item the schema tracks, or a name matched by a directory's own include_match or include_local, is kept even when it matches this list.

Type: boolean | Default: true

Whether the filesystem scanner follows links — both symbolic links and Windows directory junctions — into their targets when recursing. Enabled by default so a relocated folder (e.g. linked to another drive) is scanned transparently. A per-directory follow_links schema property overrides this default for a specific directory's children.

directory_ignore_hidden_temporary#

Type: boolean | Default: true

When true, untracked files and directories with the Windows Hidden or Temporary attribute (such as C:/ProgramData) are excluded from scans. Tracked paths are scanned regardless.

freshness_threshold#

Type: integer (sec) | Default: 300

How many seconds before cached scan data is considered stale and needs a refresh.

max_file_cache#

Type: integer (MB) | Default: 512

Maximum total size of the in-memory adapter data cache. When the limit is reached, least-recently-used entries are evicted.

capture_max_items#

Type: integer (items) | Default: 10000

Runaway brake on how many items a single capture scan may materialize before it stops descending (0 = unlimited). Guards against an accidental discovery capture over a whole drive. When the limit is hit, the capture still completes and warns; the un-scanned remainder is left in place, and re-capturing with a higher limit picks up where it left off.


Logging#

Verbosity thresholds and rotation for the log files.

Each output sink has its own threshold. Valid values for both: DEBUG, DETAIL, INFO, WARNING, ERROR. DETAIL (between INFO and DEBUG) is detailed-but-routine progress (per-container scan steps, per-subtree extraction); DEBUG is dev-only per-item detail.

log_level#

Type: string | Default: "INFO" | Allowed: DEBUG, DETAIL, INFO, WARNING, ERROR

Threshold for the log file (pinman.log). Set to DEBUG to capture per-item detail in the file (e.g. for a bug report).

progress_log_level#

Type: string | Default: "DETAIL" | Allowed: DEBUG, DETAIL, INFO, WARNING, ERROR

Threshold for the in-memory job-progress stream that feeds the UI (capture/backup progress dialog + bar). DETAIL lets the UI show per-step progress; DEBUG per-item detail is excluded regardless, so the UI never floods.

log_max_mb#

Type: integer (MB) | Default: 10

When a Pinman process starts and finds its log file larger than this, it saves the file as a timestamped copy (e.g. pinman-20260928-150604.log) and starts a fresh one. 0 = never rotate. The check runs only at startup, so a service that runs for a long time without restarting can grow past the limit until its next start. Applies to pinman.log and the service logs alike. pinman log rotate rolls pinman.log on demand; pinman log list shows the current and rotated files.

log_retention_days#

Type: integer (days) | Default: 30

Rotated log copies older than this are deleted permanently (not sent to the Recycle Bin), checked each time a process starts. 0 = keep them forever. Only the timestamped copies are ever deleted — never the current log files.


Services#

service_watchlist#

Type: list of strings | Default: (see below)

Windows service names pinned to the top of the Services tab in the UI. Default includes Audio, Themes, Windows Search, Print Spooler, Superfetch, Diagnostics Tracking, Windows Update, and Windows Defender.

[
  "Audiosrv",
  "AudioEndpointBuilder",
  "Themes",
  "WSearch",
  "Spooler",
  "SysMain",
  "DiagTrack",
  "wuauserv",
  "WinDefend"
]

Overlay#

overlay_monitor#

Type: integer | Default: 0

Which monitor shows on-screen messages and slideshows (0 = first). Takes effect on the next overlay.


Advanced#

Structured values, edited as raw JSON.

system_summary_props#

Type: object | Default: (see below)

Controls which system properties are shown at a glance in each OS category on the System tab. Keys are OS category names (e.g., "Display", "Power"); values are lists of property path strings using /-separated paths, with * as a wildcard for array items.

{
  "About": ["WindowsVersion", "CPUName", "InstalledRAM"],
  "Sound": ["Master/Volume"],
  "Personalization": ["Desktop/WallpaperPath", "ScreenSaver/Active"],
  "Display": ["System/MonitorCount"],
  "Power": ["Plan/ActivePlanName", "Timeouts/DisplaySleepAC"],
  "Network": ["ActiveAdapterName", "FirewallEnabled"],
  "GPU": ["Adapters/*/Name"],
  "Gaming": ["GameMode", "GameDVR", "HardwareAccelScheduling"],
  "Privacy & Security": ["UACLevel", "SmartScreenEnabled"],
  "Accessibility": ["HighContrast"],
  "Input": ["Keyboard/KeyboardDelay"],
  "Startup": ["AutoLogon", "ShellLauncher"],
  "Monitoring": ["MemoryUsagePercent", "CPUTemperature"]
}