remote commands

command lifecycle

Each machine has two command documents:

• sites/{siteId}/machines/{machineId}/commands/pending
• sites/{siteId}/machines/{machineId}/commands/completed

Both documents store command IDs as top-level map fields. A successful terminal write removes the matching field from pending.

command types

process management

For set_launch_mode and toggle_autolaunch, the agent matches process_id / processId first and falls back to process_name. set_launch_mode persists the requested mode and any supplied schedules.

configuration

software deployment

project distribution

Current project distribution uses roost v2 handlers registered through the agent command router:

Legacy v1 ZIP distribution still ships in the agent for older dashboard paths:

system commands

The agent does not provide a remote self-uninstall command. Remote software removal uses uninstall_software for third-party applications.

ai/cortex tools

command document structure

pending command

Written as one field inside sites/{siteId}/machines/{machineId}/commands/pending:

{
  "restart_process_machineA_1711234567890": {
    "type": "restart_process",
    "process_name": "TouchDesigner",
    "createdAt": "<server timestamp>",
    "expiresAt": "<timestamp>",
    "status": "pending"
  }
}

completed command

Merged into sites/{siteId}/machines/{machineId}/commands/completed, then removed from pending:

{
  "restart_process_machineA_1711234567890": {
    "type": "restart_process",
    "result": "Process 'TouchDesigner' restarted successfully (PID: 12345)",
    "status": "completed",
    "completedAt": "<server timestamp>"
  }
}

failed command

{
  "restart_process_machineA_1711234567890": {
    "type": "restart_process",
    "error": "Process 'TouchDesigner' not found in configuration",
    "status": "failed",
    "completedAt": "<server timestamp>"
  }
}

Progress updates are also merged into the completed document under the same command ID with fields such as status, progress, deployment_id, and updatedAt. Terminal states include completed, failed, and cancelled.

command polling (dashboard)

When the web API queues a command, POST /api/sites/{siteId}/machines/{machineId}/commands accepts type, params, and optional timeout_seconds, then returns 202 with {commandId, status: "pending"}.

Poll GET /api/sites/{siteId}/machines/{machineId}/commands/{commandId} for the command result. The status route returns pending, in_progress, completed, failed, or a 404/timeout. Cortex tool execution polls completion internally about every 1.5 seconds.

software installation flow

The install_software command triggers a multi-step process:

1. Download installer to the agent temp installer directory.
   Progress: downloading 0% to 100%

2. Verify sha256_checksum.
   Missing or mismatched checksums fail the command before execution.

3. Optionally stop conflicting processes and suppress managed projects.
   Controlled by close_processes and suppress_projects.

4. Execute installer with silent flags in the interactive user's session.
   Progress: installing, then waiting for exit code.

5. Verify installation if verify_path is provided or derived from /DIR.

6. Cleanup temp file, release install locks, and sync software inventory.

install_software payload

supported installer types

project distribution flow

roost v2 sync

The sync_pull command is the current distribution path:

1. Validate required site, roost, version, URL, and target-root fields.
2. Check the site-level roost kill switch.
3. Report the target state as pending.
4. Mint a fresh version download URL when the Firebase client can do so.
5. Fetch and validate the version manifest.
6. Diff against the most recent local committed version for that roost.
7. Register or resume a local distribution row.
8. Download missing chunks with throttled progress updates.
9. Assemble files atomically into extract_root.
10. Commit the distribution and report final target state.

cancel_sync looks up the matching in-flight distribution by site_id, roost_id, and version_id, then signals its cancellation event. rollback_to_version reuses the same sync_pull path; the server-side roost rollback has already selected the older version.

legacy v1 ZIP distribution

distribute_project remains available for older dashboard paths only. It downloads a ZIP archive, extracts it to extract_path or the default Owlette projects directory, optionally checks expected extracted paths, cleans up the ZIP, and reports progress with the legacy distribution_id.

system command details

reboot / shutdown

Manual reboot and shutdown commands do not accept configurable countdown fields. The agent sets local shutdown intent, announces the state to Firestore, then invokes Windows with a fixed 30-second countdown:

subprocess.run(['shutdown', '/r', '/t', '30', '/c', 'owlette remote reboot requested'])
subprocess.run(['shutdown', '/s', '/t', '30', '/c', 'owlette remote shutdown requested'])

cancel_reboot aborts the pending OS countdown with shutdown /a and clears the dashboard flags when Firestore is available.

self-update

update_owlette requires installer_url and checksum_sha256. The agent derives target_version from the payload or URL, downloads the installer to C:\ProgramData\owlette\tmp, verifies the checksum, writes an update marker, and launches the installer through a one-time scheduled task running as SYSTEM. A recovery scheduled task attempts to restart the service if it does not return after the update.