agent commands reference

command lifecycle

Command queues are single Firestore documents whose fields are command IDs. They are not per-command subcollections.

1. Web/API writes one map entry to:
   sites/{siteId}/machines/{machineId}/commands/pending

   {
     "{commandId}": {
       "type": "command_type",
       "status": "pending",
       ...command-specific fields
     }
   }

2. The agent listener reads the pending document and dispatches each unseen
   command ID.

3. Long-running commands can write partial records to:
   sites/{siteId}/machines/{machineId}/commands/completed

4. The agent writes the final record under the same command ID in the
   completed document, then deletes the command ID field from pending.

Server helpers that use stampCommand add createdAt, expiresAt, and optional auditCorrelationId. The public machine-command endpoint also stamps siteId, machineId, timestamp, status, and queuedBy.

command document schema

pending entry

{
  "{commandId}": {
    "type": "command_type",
    "status": "pending",
    "createdAt": "<server timestamp>",
    "expiresAt": "<timestamp>",
    "timestamp": "<server timestamp>",
    "queuedBy": "user:uid-or-apiKey:keyId",
    "...": "command-specific fields"
  }
}

Legacy writers may use millisecond timestamp without createdAt or expiresAt; the agent accepts both shapes.

progress entry

Long-running commands update the completed document before final completion.

{
  "{commandId}": {
    "status": "downloading",
    "updatedAt": "<server timestamp>",
    "deployment_id": "deployment_123",
    "progress": 45
  }
}

Progress writes are partial status records. They are throttled by the agent and can use command-specific statuses such as downloading, installing, uninstalling, or extracting before the final completed, failed, or cancelled record is written.

completed entry

{
  "{commandId}": {
    "type": "command_type",
    "result": "Human-readable result message",
    "status": "completed",
    "completedAt": "<server timestamp>",
    "deployment_id": "deployment_123"
  }
}

failed entry

Failed commands use error, not result.

{
  "{commandId}": {
    "type": "command_type",
    "error": "Error: description of what went wrong",
    "status": "failed",
    "completedAt": "<server timestamp>",
    "deployment_id": "deployment_123"
  }
}

cancelled entry

{
  "{commandId}": {
    "type": "command_type",
    "result": "Cancellation message",
    "status": "cancelled",
    "completedAt": "<server timestamp>",
    "deployment_id": "deployment_123"
  }
}

public API command types

These are the command types accepted by the public machine-command action in web/lib/actions/executeMachineCommand.server.ts.

process control

The public route shim still requires process_name for set_launch_mode; direct Firestore command writers and the agent handler accept process_id / processId as the preferred identifier.

machine power and reboot state

screenshots and live view

display topology

cortex and agent update

mcp_tool_call returns JSON-encoded tool output in the final result field when the command completes successfully.

legacy dashboard and internal command types

These commands are still registered in agent/src/owlette_service.py but are not all accepted by the public machine-command allowlist. They exist for dashboard flows, deployment workers, older configuration flows, or internal admin actions.

configuration and process compatibility

software deployment

legacy project distribution

router-registered roost v2 command types

These commands are registered in agent/src/sync_commands.py through CommandRouter and dispatch before the legacy if/elif chain.

sync_pull

Pull an immutable roost version, download missing chunks, and assemble files at the target path.

The handler reports target states pending, downloading, assembling, committed, failed, and cancelled.

cancel_sync

Cancel an in-flight sync_pull for the same site, roost, and version.

Cancellation is cooperative. The active download or file operation finishes its current step, then the handler records cancelled.

rollback_to_version

Materialize an older roost version after the server-side rollback has already changed the current-version pointer. The payload matches sync_pull.

coverage checklist

Dispatcher entries covered from agent/src/owlette_service.py:

restart_process, start_process, kill_process, stop_process, toggle_autolaunch, set_launch_mode, update_config, install_software, update_owlette, cancel_installation, uninstall_software, cancel_uninstall, refresh_software_inventory, distribute_project, cancel_distribution, mcp_tool_call, capture_screenshot, reboot_machine, shutdown_machine, cancel_reboot, dismiss_reboot_pending, provision_cortex_key, start_live_view, stop_live_view, apply_display_topology, enumerate_display_modes, ack_display_topology, and test_display_apply.

Router entries covered from agent/src/sync_commands.py:

sync_pull, cancel_sync, and rollback_to_version.