configuration

Desktop app and dashboard writes apply immediately; the agent picks up config changes on a polling listener with a 2-10 second interval.

When the desktop app is open, launch mode and schedule labels refresh from external dashboard or service changes. Text fields that are actively focused defer remote refresh until focus leaves.

the desktop app

The desktop app runs as a separate process from the service. Launch it from:

• System tray -> Right-click -> open owlette
• Start Menu -> Owlette
• Directly: C:\ProgramData\Owlette\app\owlette-desktop.exe

what the window shows

Nothing has been configured yet on a freshly enrolled machine:

The menu at the top right is where a machine joins its first site, or leaves the one it is on:

Joining shows a pairing phrase to approve from any device — the same device-code flow the installer uses:

config.json

The configuration file is stored at C:\ProgramData\Owlette\config\config.json.

When no config exists, the agent generates this default structure:

{
    "version": "1.7.0",
    "environment": "production",
    "processes": [],
    "logging": {
        "level": "INFO",
        "max_age_days": 90,
        "firebase_shipping": {
            "enabled": false,
            "ship_errors_only": true
        }
    },
    "sentry": {
        "enabled": false,
        "dsn": ""
    },
    "displays": {
        "enabled": true,
        "assigned": null,
        "auto_enforce": false,
        "remoteApplyEnabled": false
    },
    "temperature": {
        "enabled": true
    },
    "watchdog": {
        "enabled": true,
        "thresholds": {
            "failure_seconds": 360,
            "boot_grace_seconds": 180
        },
        "budget": {
            "max_per_window": 3,
            "window_seconds": 3600
        },
        "preconditions": {
            "require_internet": true,
            "fatal_error_suppression_seconds": 3600
        }
    }
}

If the agent regenerates a config and an existing firebase section is present, it preserves that section so pairing credentials are not lost.

top-level fields

logging fields

user-editable sections

process configuration

A process's launch mode is the first thing to set: off leaves it alone, always on keeps it running around the clock and relaunches it if it crashes, and scheduled runs it inside the windows you define.

The pencil button on the right edge of the launch-mode control opens the schedule editor. It is offered in every launch mode — editing from off or always on stores the windows without changing the mode. Times follow the site's timezone, or this machine's local time when it is not paired to one:

Each process in the processes array uses the current process keys. The generator creates an empty array; entries created in the desktop app and entries created from the dashboard share most fields but are not identical.

Desktop-app-created entry:

{
    "id": "b8f1a4d2-8b1e-4df9-b7ff-7d4c3c10f9f1",
    "name": "TouchDesigner",
    "exe_path": "C:\\Program Files\\Derivative\\TouchDesigner\\bin\\TouchDesigner.exe",
    "file_path": "C:\\Projects\\MyProject.toe",
    "cwd": "C:\\Projects",
    "priority": "Normal",
    "visibility": "Show",
    "time_delay": "0",
    "time_to_init": "10",
    "relaunch_attempts": "5",
    "launch_mode": "off",
    "autolaunch": false,
    "schedules": null
}

Dashboard-created entry:

{
    "id": "b8f1a4d2-8b1e-4df9-b7ff-7d4c3c10f9f1",
    "processId": "b8f1a4d2-8b1e-4df9-b7ff-7d4c3c10f9f1",
    "name": "TouchDesigner",
    "exe_path": "C:\\Program Files\\Derivative\\TouchDesigner\\bin\\TouchDesigner.exe",
    "file_path": "C:\\Projects\\MyProject.toe",
    "cwd": "C:\\Projects",
    "priority": "Normal",
    "visibility": "Normal",
    "time_delay": "0",
    "time_to_init": "10",
    "relaunch_attempts": 3,
    "launch_mode": "off",
    "autolaunch": false,
    "schedules": null
}

Dashboard writes include schedulePresetId only when a schedule preset is supplied.

process fields

visibility options

The desktop app exposes Normal and Hidden. The launcher also accepts Minimized and Maximized when a process entry is edited manually.

Show and Hide values are normalized by the service to Normal and Hidden.

web-based configuration

From the dashboard, you can edit process settings remotely:

1. Click on a machine in the dashboard.
2. Click the process row's pencil/edit button.
3. Edit settings such as name, paths, priority, visibility, delays, launch mode, and schedules.
4. Click save changes.

The dashboard writes process updates to Firestore. The agent listener applies the new configuration locally and writes the updated config file without requiring a service restart.

configuration sync

• Desktop app -> service: The desktop app writes to config.json; the service detects the file change.
• Service -> Firestore: The service uploads local config changes.
• Firestore -> service: The service listener applies remote config changes.
• Dashboard -> Firestore: The dashboard writes config changes directly to Firestore.
• Hash tracking prevents feedback loops when a local config change is echoed back from Firestore.