Documentation

The full configuration reference for Ratatoskr — dialogs, workflows, triggers, and the CLI.

Overview

Ratatoskr shows information and collects input from macOS users, driven by your MDM. Dialogs and workflows are defined declaratively in a configuration profile and evaluated DDM-style — Ratatoskr keeps reminding until the goal is reached — and it responds to many kinds of triggers, not just a script invocation.

Requirements

• macOS 26 or later
• Universal binary — Apple Silicon and Intel
• Jamf Pro for the ready-made schema/Extension Attributes (any MDM can deploy the underlying profile and pkg)

Installation & Deployment Order

Deploy in this order — the Managed Login Items profile first, so macOS never shows the user a "background item added" alert for an app that isn't approved yet:

Config changes apply within about 10 seconds of profile install/change/removal; removing a profile cancels any pending or showing dialog it defined. Uninstall with sudo "/Library/Application Support/Ratatoskr/uninstall.sh" (add --keep-data to preserve state).

How Configuration Works

Ratatoskr reads Managed Preferences at the domain com.spectrechen.Ratatoskr, holding Settings, Branding, Scripts, Dialogs, Workflows, and Conditions. Only computer-level managed preferences are trusted for Scripts — user-level preferences may define dialogs/workflows, but never scripts.

"Settings": {
  "LogLevel": "info",                 // debug | info | notice | error
  "LoginGracePeriodSeconds": 60,
  "PresentationDeferralMaxMinutes": 60,
  "RespectFocusAndPresenting": true,
  "StatusRetentionDays": 90,
  "JamfBinaryPath": "/usr/local/bin/jamf",
  "LoginWindowNoticesEnabled": true,
  "MaxMediaSizeMB": 500
}

Domains & Merging

Beyond the main domain, additional domains named com.spectrechen.Ratatoskr.<suffix> — e.g. com.spectrechen.Ratatoskr.wf.macos-update — can each carry their own Dialogs/Workflows/Scripts/Conditions. The daemon merges every domain, because macOS itself won't merge the same key across two profiles targeting one domain. This is exactly how Jamf's per-workflow custom schema (Jamf/ratatoskr-workflow-schema.json) works — one workflow, one profile, one domain.

IDs must be unique across every merged domain. On a collision, the main domain wins, then whichever domain sorts alphabetically first — and an error is logged either way, so a collision is never silent.

Localization & Placeholders

Any text field accepts a plain string, or a per-language object:

{ "en": "Your Mac needs an update.", "de": "Dein Mac braucht ein Update.", "default": "en" }

Ratatoskr picks a variant from Locale.preferredLanguages, falling back to default, then en, then the first entry present.

Placeholders, substituted at presentation time:

{{env.KEY}} only resolves for CLI calls, from a RATATOSKR_VAR_KEY environment variable.

Styles

A loginwindow notice — no buttons, no fields, just information before the user even logs in.

Content & Media

Message text supports Markdown. Media items can be an SF Symbol, inline base64 data, an MDM-deployed file path, or a remote URL — each optionally with a light/dark variant and a fallback:

{ "SFSymbol": "exclamationmark.shield.fill", "Color": "#FF9F0A", "Effect": "pulse" }
{ "Data": "<base64>", "Type": "png" }                       // inline, keep it under ~200 KB
{ "Path": "/Library/Application Support/Acme/banner.png", "Fallback": { "SFSymbol": "..." } }
{ "URL": "https://cdn.acme.com/intro.mp4", "SHA256": "...", "Fallback": { "SFSymbol": "..." } }
{ "Light": { "SFSymbol": "sun.max" }, "Dark": { "SFSymbol": "moon.stars" } }

Supported media: PNG, JPEG, HEIC, GIF (animated), PDF, MP4/MOV, Markdown, and web pages (host must be in AllowedMediaHosts). SVG is not supported. SF Symbol effects: pulse, bounce, breathe, wiggle, rotate.

Markdown message content — lists, bold, italics, code, and links, rendered natively.

Input Fields

Field types: text, textarea, secure (never logged or stored — delivered only to CLI stdout), number, dropdown, radio, checkbox, toggle, and date.

{ "ID": "assetTag", "Type": "text", "Label": "Asset tag", "Placeholder": "A-12345",
  "Required": true, "Regex": "^A-\\d{5}$", "RegexError": "Format A-12345",
  "Help": "Format: A- followed by 5 digits",
  "Info": "Printed on the **sticker** under your Mac" }

A field with "Report": true has its value copied into status.plist/the Jamf Extension Attribute — never possible for secure fields. A button with "Validates": true only becomes active once every field on the dialog is valid.

Every field type at a glance — note the ⓘ next to "Cost center", opening the Info popover.

Button Actions

Up to 4 buttons per dialog (or 4 action buttons on a banner). Each button runs zero or more actions:

Scripts run via RunScript receive RATATOSKR_BUTTON, RATATOSKR_FIELD_<ID> (never for secure fields), RATATOSKR_USER, and RATATOSKR_WORKFLOW as environment variables; stdout/stderr are captured to the log, truncated at 64 KB.

Triggers

A network trigger can match on more than just "connected" — a specific DNS search domain, a reachable host, the default gateway, an interface type, or (opt-in) SSID:

{ "Any": [
    { "DNSSearchDomain": "corp.acme.com" },
    { "HostReachable": "intranet.corp.acme.com", "Port": 443, "ExpectHTTPStatus": 200 },
    { "DefaultGateway": "10.1.0.1" },
    { "InterfaceType": "vpn" },
    { "SSID": "ACME-Corp" }
] }

Conditions

Conditions gate eligibility and completion. Types: osVersion, fileExists, appInstalled (bundle ID + optional minimum version), profileInstalled, processRunning, script (exit 0 = true), network (a NetworkMatch), uptimeDays, diskFreeGB, batteryPercent, onACPower, consoleUserIn, plus always/never. Operators: == != < <= > >=. Combine with { "All": [...] }, { "Any": [...] }, or { "Not": ... }, referencing condition IDs or nesting them inline.

{ "ID": "os-current", "Type": "osVersion", "Operator": ">=", "Value": "26.1" }

Escalation & Deferral

A workflow references one dialog per stage, escalating as conditions are met:

{
  "ID": "macos-update-26-1",
  "Version": 3,
  "Triggers": [ "login", "unlock", "wake",
                { "Type": "schedule", "Interval": "4h" } ],
  "Stages": [
    { "DialogID": "update-soft", "Until": { "DeferralsUsed": 3 } },
    { "DialogID": "update-firm", "Until": { "Before": "2026-10-15T09:00:00Z" } },
    { "DialogID": "update-block" }
  ],
  "Deferral": { "MaxDeferrals": 5, "Deadline": "2026-10-20T17:00:00Z" },
  "Completion": {
    "ButtonIDs": ["update"],
    "RequireConditionAfterButton": true,
    "Condition": "os-current"
  },
  "OnComplete": [ { "Type": "JamfPolicy", "Event": "recon" } ]
}

The current stage is the first one whose Until isn't yet met — by deferrals used, a deadline, or a run count. Once the deadline passes, Ratatoskr jumps straight to the last stage and hides any Defer buttons. Before presenting anything, the completion condition is checked first — if it's already true, the workflow completes silently without ever showing a dialog. That's self-healing: fix the underlying problem some other way, and Ratatoskr stops nagging on its own.

Bumping Version, removing the profile, or running sudo ratatoskr reset <id> all clear a workflow's state and start it over. Deferral-only buttons never complete a workflow on their own.

Stage 1 — soft.

Stage 3 — block. The deadline passed; no more deferring.

(Stage 2 — firm — is the one shown at the top of the product page.)

Presentation Policy

• One dialog at a time per user session, queued by priority (critical > high > normal > low), then by queue time.
• critical dialogs show immediately, ignoring Focus/presenting detection and the login grace period — but still wait behind another already-showing critical dialog.
• With RespectFocusAndPresenting on, non-critical dialogs wait (up to PresentationDeferralMaxMinutes) while a presenter/conferencing app holds a display-sleep-prevention assertion, or the frontmost app is full screen and on the "presenting" list.
• A grace period after login/unlock/wake, set by LoginGracePeriodSeconds, delays non-critical dialogs briefly so the user isn't hit with a dialog the instant they sit down.
• fullscreen hides the Dock and menu bar, but Force Quit stays available per Apple's own guidelines — and if the agent is force-quit, launchd restarts it and the dialog reappears.

CLI Commands

* A non-root caller may only show a dialog without RunScript/JamfPolicy actions, and may only trigger a workflow marked "UserTriggerable": true.

ratatoskr show --title "Hello" --message "Your Mac is **ready**." --icon sf:checkmark.seal.fill \
  --button1 "Great" --button2 "Help" --timeout 300
echo $?   # 0 = Great, 2 = Help, 4 = timeout

ratatoskr validate my-workflow.json
ratatoskr preview my-workflow.json --workflow my-workflow --stage 1     # interactive window
ratatoskr preview my-workflow.json --dialog soft --snapshot soft.png --dark

Exit Codes

Reporting & Logging

State lives in /Library/Application Support/Ratatoskr/State/, one JSON file per workflow, root-only. A read-only summary for Jamf Extension Attributes and other tools lives at status.plist — it contains no field values unless a field has "Report": true. JamfPolicy actions and OnComplete run jamf policy -event <name> as root.

Unified logging under the subsystem com.spectrechen.Ratatoskr, plus a rotating file log (10 MB × 5 files) in /Library/Application Support/Ratatoskr/Logs/ratatoskr.log. Dynamic values are private by default; IDs and states are public. Secure field values and script content are never logged, anywhere.

ratatoskr logs --last 10m
log show --predicate 'subsystem == "com.spectrechen.Ratatoskr"' --info --debug --last 1h

Example Configurations

Five ready-to-read example configs, included in the full deployment bundle as both raw JSON and pre-converted .mobileconfig files:

Convert your own JSON into a ready-to-upload profile:

ratatoskr validate my-workflow.json
Scripts/make-mobileconfig.py my-workflow.json \
  --domain com.spectrechen.Ratatoskr.wf.my-workflow \
  -o my-workflow.mobileconfig

Policy Scripts

10 self-contained Jamf policy scripts ship in the deployment bundle's Jamf/scripts/ — each supports DRY_RUN=1 for local testing (prints the dialog JSON, skips side effects like restarting or writing state) and reads Jamf script parameters 4 and up for its settings:

Troubleshooting

Set Settings.LogLevel to debug for maximum detail. As always: secure field values and script contents are never written to any log.