@littlevoid/ziptie

v1.3.1

Published

a month ago

Windows 11 kiosk and exhibit PC bootstrap utility.

0High
0Medium
0Low

ziptie

Windows 11 system setup and bootstrapping CLI for museum exhibits, gallery installations, and unattended digital signage. Hardens and configures Windows settings offline from a declarative configuration file.

Quick start

One-line online install (requires internet)

Run from PowerShell on a fresh machine to bootstrap directly from GitHub:

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/littlevoid-io/ziptie/main/scripts/bootstrap.ps1 | iex"

Add to existing repository (can be configured for offline deployment, requires npm installed)

Initialize in your exhibit project root:

npx @littlevoid/ziptie init

Prompts for target mode (online, offline, npm), scaffolding ziptie.config.json and ziptie-setup.bat. Run on target exhibit machines with:

.\ziptie-setup.bat

Commands

Setup commands

| Command | Description | | ------------------------------- | ----------------------------------------------------------- | | ziptie | Apply configuration (prompts for elevation if not elevated) | | ziptie --dry-run (-d) | Preview changes without modifying system state | | ziptie --undo (-u) | Revert applied configuration | | ziptie --yes (-y) | Auto-confirm prompt with a 10s countdown | | ziptie --config <path> (-c) | Specify a custom configuration file path |

When developing from checkout, run npm start -- <flags>.

Init command

| Command | Description | | ----------------------------------- | ----------------------------------------------------- | | ziptie init | Scaffolds ziptie.config.json and ziptie-setup.bat | | ziptie init --mode <mode> (-m) | Set execution mode: online, offline, or npm | | ziptie init --force (-f) | Overwrite existing configuration and batch files | | ziptie init --project-root <path> | Target directory for scaffolding (default: cwd) |

Passing flags & overrides

In an exhibit repository (`ziptie-setup.bat` / CLI)

Pass standard flags, flat parameter shortcuts, or dot-notation overrides:

# Safe preview with auto-confirm
.\ziptie-setup.bat -y -d

# Flat shortcuts for unique keys
.\ziptie-setup.bat --timezone "Tokyo Standard Time" --disableScreensaver false --apps "Node.js,Git.Git"

# Dot-notation for nested categories
.\ziptie-setup.bat --windows.disableScreensaver=false --system.computerName="EXHIBIT-99"

Via one-line online install (`bootstrap.ps1`)

Pass parameters to the remote runner using -ExtraArgs:

powershell -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://raw.githubusercontent.com/littlevoid-io/ziptie/main/scripts/bootstrap.ps1))) -ExtraArgs '-y -d --timezone \"Tokyo Standard Time\" --disableScreensaver false'"

Configuration

ziptie.config.json is validated against ziptie.schema.json and merged over defaults in ziptie.default.config.json:

{
  "$schema": "https://raw.githubusercontent.com/littlevoid-io/ziptie/main/ziptie.schema.json",
  "system": {
    "computerName": "auto",
    "timezone": "auto",
    "dailyReboot": true,
    "rebootTime": "06:00"
  },
  "autologon": {
    "enabled": true,
    "username": "auto",
    "disablePasswordlessHello": true
  },
  "startupTask": {
    "enabled": true,
    "workingDir": "auto",
    "executable": "launch.bat"
  }
}

Config sections

All sections are optional and merge over defaults in ziptie.default.config.json:

| Section | Default | Purpose | | ---------------- | ------- | --------------------------------------------------------------------------------- | | system | on | Hostname, timezone, daily reboot task, reboot on finish | | autologon | on | Auto-login credentials and Windows Hello bypass | | startupTask | on | Scheduled task registered to trigger AtLogon in the GUI session | | packageManager | on | Winget/Chocolatey installs and offline ./installers scanning | | windows | on | System tweaks: telemetry, updates, widgets, touch gestures, power plan, bloatware |

Execution pipeline

| Stage | Action | | :----------------------- | :----------------------------------------------------------------------------------------------- | | 1. Config resolution | Parses ziptie.config.json against ziptie.schema.json and deep-merges over defaults | | 2. Hive mount | Mounts C:\Users\Default\NTUSER.DAT to HKU:\DefaultUser to propagate settings to new accounts | | 3. App provisioning | Scans ./installers for silent installers or resolves packages via Winget/Chocolatey | | 4. OS settings | Executes convergent scripts in scripts/windows/ for apply or revert (--undo) | | 5. Shell restart | Unmounts default hive and restarts Windows Explorer |

Development

npm install
npm run build         # bundle CLI into dist/index.js
npm test              # run unit and pester tests
npm run package       # compile standalone dist/ziptie.exe and zip archive

Windows Sandbox testing

Verify configuration behaviors inside an isolated Windows Sandbox:

| Command | Action | | ------------------------ | -------------------------------------------------------- | | npm run sandbox | Mount repository and open interactive guest console | | npm run sandbox:local | Run automated guest tests (test/run-sandbox-tests.ps1) | | npm run sandbox:remote | Test remote cloud bootstrap script in clean sandbox |

License

MIT