configuration

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

When the GUI 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.

configuration gui

The GUI is a CustomTkinter application that runs as a separate process from the service. Launch it from:

• System tray -> Right-click -> open owlette
• Start Menu -> Owlette Configuration
• Directly: C:\ProgramData\Owlette\python\pythonw.exe C:\ProgramData\Owlette\agent\src\owlette_gui.py

gui features

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.6.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
    },
    "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

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

GUI-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 local GUI 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

• GUI -> service: The GUI 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.