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

what the footer's status word means

The footer resolves to one of seven words, in this order — the first one that fits wins:

The status dot and the word share one tone: muted for checking and disabled, green for connected, amber for authentication required, and red for the rest.

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:

Leaving is the one destructive local action: the service is stopped while the machine is deregistered and then started again — Windows asks you to approve that — and pairing the machine again needs a fresh phrase.

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. Windows are wall-clock times: by default they run on the machine's own clock, so a 9am window means 9am where the machine sits, even for a fleet spread across timezones. A site that has opted in to site time is the exception — its machines evaluate windows in the site's timezone instead. See timezones for which parts of owlette use site time:

how to run holds the fields you set once and rarely revisit, so it starts folded. Open it to reach attempts, priority and visibility:

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": "Normal",
    "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

For an executable that commonly runs many instances at once — node.exe, python.exe, TouchDesigner.exe — file_path (the desktop app's path / args field) does more than pass an argument: because the value appears in the process's command line, it is what lets owlette identify this entry's process among look-alikes before it has ever launched it. With it blank, owlette does not guess between identical instances — it launches its own instance and manages that. See managed or inherited.

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.