cortex tools reference

tier system

Server-side tools (get_site_logs, get_system_presets, deploy_software, update_process, add_process, delete_process) execute in the Next.js server process. They do not route through the agent command queue.

execution-mode matrix

Web Cortex chooses an execution path by tool name in web/lib/cortex-utils.server.ts. Server-side tools run in the Next.js server process. Legacy command tools write existing machine command types. Firestore tools create mcp_tool_call entries for the agent to execute. Local Agent SDK MCP is separate: agent/src/cortex_tools.py exposes only the tools returned by _make_tier1_tools, _make_tier2_tools, and _make_tier3_tools.

Local Agent SDK coverage is intentionally smaller than the web registry: at maximum tier it returns 21 tools, and at the default max_tier=2 it returns 15. agent/src/cortex_tools.py defines a get_gpu_processes wrapper, but the function is omitted from the returned tier-1 list, so local Agent SDK Cortex does not expose it today. agent/src/mcp_tools.py also contains internal handlers that are not public web Cortex tools, including get_display_layout and apply_display_topology.

tier 1: read-only tools

get_site_logs

Get activity logs across all machines in the site. Useful for finding errors, crashes, and events across the fleet. Server-side — queries Firestore directly.

get_system_info

Get comprehensive system information including hostname, OS (with correct Windows 10/11 detection), CPU model and usage, memory (used/total GB), disk (used/total GB), GPU model, driver version, VRAM (used/total GB), GPU load %, uptime, and agent version.

get_process_list

Get all owlette-configured processes with their current status, PID, launch mode, executable path, file path / command arguments, working directory, and whether they are running.

get_running_processes

Get all running OS processes with CPU and memory usage. Can filter by name.

Returns: Processes sorted by memory usage with name, PID, CPU%, memory%.

get_gpu_processes

Get per-process GPU memory (VRAM) usage via Windows Performance Counters — same data source as Task Manager. Shows dedicated and shared GPU memory per process, sorted by usage. Works cross-vendor (NVIDIA, AMD, Intel) and for all GPU APIs (DirectX, OpenGL, CUDA, Vulkan).

get_network_info

Get network interfaces with IP addresses, netmasks, and link status.

get_disk_usage

Get disk usage for all drives including total, used, free space and percentage.

get_event_logs

Get Windows event log entries from Application, System, or Security logs.

get_service_status

Get the status and start type of a Windows service. Returned start_type disambiguates "stopped" states: automatic (should be running), demand_start (stopped-is-normal idle state, e.g. wuauserv/BITS), disabled (intentionally off).

get_agent_config

Get the current owlette agent configuration (sensitive fields stripped).

get_agent_logs

Get recent owlette agent log entries.

get_agent_health

Get agent health status including connection state and health probe results.

get_system_presets

Get available software deployment presets managed by the site admin. Returns installer URLs, silent install flags, verification paths, and other deployment parameters for software like TouchDesigner, Unreal Engine, media players, etc. Use this before deploy_software to find the correct preset and parameters. Server-side — queries Firestore directly.

check_pending_reboot

Detect whether a system reboot is currently pending (from Windows Update, Component Based Servicing, pending file rename operations, or SCCM client). Read-only diagnostic — use during incident investigations, after a suspected update, or when the machine is behaving unusually. The agent also emits a site-level auto-alert the first time it detects a pending reboot (idempotent via a flag file).

Returns: pending (bool), reasons (array), last update install time, next scheduled update run time (if available).

tier 2: process & machine management tools

These execute immediately without user confirmation. Owlette-configured process control tools (restart_process, kill_process, start_process, set_launch_mode) wrap existing commands. Process config tools (update_process, add_process, delete_process) run server-side through the same validated action functions as the dashboard. The rest are purpose-built with validated parameters and narrower blast radius than raw shell scripts.

restart_process

Restart an owlette-configured process by name.

kill_process

Kill/stop a running owlette-configured process.

start_process

Start a stopped owlette-configured process.

set_launch_mode

Set the launch mode for a process.

Schedule block format:

{
  "days": ["mon", "tue", "wed", "thu", "fri"],
  "ranges": [
    { "start": "09:00", "stop": "18:00" }
  ]
}

update_process

Update an owlette-configured process by name. Only fields provided in the tool call are changed. Runs server-side through updateProcess; the agent picks up the config change through the existing config listener and launch-mode diff.

add_process

Create a new owlette-managed process on the target machine. Runs server-side through createProcess; the new process defaults to launch_mode: "off" unless a launch mode is supplied.

delete_process

Delete an owlette-configured process by name. Runs server-side through deleteProcess. Deleting a process removes it from the machine config; it does not terminate an already-running OS process. Use kill_process first when the running process should also be stopped.

capture_screenshot

Capture a screenshot of the remote machine's desktop. Returns the image for visual analysis — use to diagnose display issues, verify process state, or see what's currently on screen.

manage_process

Kill, suspend, or resume OS processes by name pattern. Works on any process, not just Owlette-managed ones. Safer than run_command + taskkill: validated params, no shell, refuses to touch critical system processes (lsass, winlogon, csrss, etc.) via an internal blocklist.

manage_windows_service

Full services.msc parity — start, stop, restart, pause/continue, set startup type, configure failure recovery, or get full service details in one call. Use set_recovery to configure auto-restart on crash (critical for unattended media installations). Use get_details to query status, startup type, binary path, dependencies, and recovery config at once.

configure_gpu_tdr

Configure Windows GPU Timeout Detection and Recovery. Writes TdrDelay (and optionally TdrDdiDelay) to the registry. Critical for TouchDesigner / Unreal / Unity installations with heavy shader work — the default 2-second timeout causes silent crashes on complex GPU operations. A reboot is required for changes to take effect.

manage_windows_update

Pause, resume, or schedule Windows Update. Pause before live events; use set_active_hours to block auto-reboot during quiet hours; set_scheduled_install for exact install timing; set_feature_deferral / set_quality_deferral to delay rollouts. Windows Update is the #1 threat to unattended 24/7 installations.

manage_notifications

Control Windows toast notifications and Focus Assist. Essential for kiosks and video walls where a surprise "Updates are ready" toast would interrupt an exhibit. Use disable_all_toasts to fully silence the system, enable_focus_assist with alarms_only for total silence, or disable_for_app to silence a specific app.

configure_power_plan

Set Windows power plan and disable sleep/hibernate/screen blanking. Required for any 24/7 unattended installation — default power settings will sleep the machine, blank the screen, or hibernate, all of which break live deployments.

manage_scheduled_task

Full Task Scheduler parity — list, enable, disable, delete, run_now, stop, create new tasks, get details, and get run history. Use create for weekly memory-flush reboots, boot-time media app launches, or event-triggered restarts.

network_reset

Flush DNS, renew IP lease, restart a network adapter, or reset the winsock stack. Common fix for NDI dropouts, Firebase connectivity loss, DNS resolution issues at venue networks. reset_winsock requires a reboot to fully take effect.

registry_operation

Read, write, or delete Windows registry values. Restricted to an allowlist of safe registry paths (Winlogon, GraphicsDrivers, WindowsUpdate, Notifications, Power, Services, etc.) — system hives like SAM, SECURITY, and Cryptography are blocked.

clean_disk_space

Clean temp files, Windows temp, prefetch cache, recycle bin, or Owlette logs with an age filter. Use dry_run=true to preview what would be deleted.

get_event_logs_filtered

Fast filtered event log query via Get-WinEvent -FilterHashtable. Orders of magnitude faster than get_event_logs when searching for specific crashes, process sources, or event IDs.

manage_windows_feature

Add, remove, or list Windows Optional Features (DISM, e.g. NetFx3, OpenSSH-Server), Windows Capabilities (FoD, e.g. OpenSSH.Client), or AppX Packages (Store apps like OneDrive, Xbox Game Bar, Cortana, Teams). Critical features for Owlette itself are blocklisted and cannot be disabled. AppX install is not supported.

show_notification

Display an on-screen message on the remote machine — useful when a technician is physically nearby. Toast style is a subtle corner notification; modal style uses msg.exe to block the screen briefly. Opposite of manage_notifications, which suppresses notifications.

tier 3: privileged tools

These require explicit user confirmation before execution.

run_command

Execute a shell command on the remote machine.

Returns: stdout, stderr, exit code.

Allowed commands (first word must be one of):

ipconfig, systeminfo, hostname, whoami, tasklist, netstat, ping, tracert, nslookup, dir, type, echo, set, ver, wmic, sc, net, reg, nvidia-smi, dxdiag

This is the default set (DEFAULT_ALLOWED_COMMANDS); it is overridable via config.mcp.allowed_commands.

run_powershell

Execute a PowerShell command on the remote machine.

Returns: stdout, stderr, exit code.

No command restrictions — every invocation is audit-logged to the site events feed and the local [MCP-AUDIT] log. Fixed 25-second timeout; for long-running work use execute_script.

run_python

Execute Python code on the remote machine in the user's desktop session.

Sandboxed execution (since v2.6.5). When invoked via this tool, code runs with:

• Restricted __builtins__ — eval, exec, compile, globals, locals, breakpoint, input, exit, quit are all removed. open, print, getattr/setattr, and common types/exceptions remain available.
• Gated imports — only a curated subset of the standard library is importable: math, json, re, datetime, time, random, collections, itertools, functools, operator, string, textwrap, decimal, fractions, statistics, copy, pprint, base64, hashlib, hmac, struct, io, csv, pathlib, typing, dataclasses, enum, abc. Dangerous modules — os, subprocess, shutil, ctypes, socket, and third-party packages like psutil or mss — raise ImportError with guidance to use execute_script or run_command instead.
• No filesystem access beyond output_dir — the code can open() files it writes into the provided output_dir variable, but cannot reach the rest of the filesystem without going through a gated import.

The LLM cannot escape this sandbox. Internal first-party callers (e.g. the agent's own screenshot capture path in agent/src/session_exec.py) pass trusted=True, which restores full builtins and unrestricted imports; that flag is not reachable from the LLM-exposed tool schema.

Returns: stdout from print(), plus any files written to output_dir.

read_file

Read the contents of a file on the remote machine.

write_file

Write content to a file on the remote machine.

list_directory

List the contents of a directory with file sizes and modification dates.

execute_script

Execute a PowerShell script on the remote machine with no command restrictions. Use for software installs, diagnostics, stress tests, service management, registry edits, or any other admin task. For most routine sysadmin scenarios, prefer a purpose-built Tier 2 tool (e.g. manage_windows_service, registry_operation, clean_disk_space) — execute_script is the escape hatch when no purpose-built tool fits.

Returns: stdout, stderr, exit code.

deploy_software

Deploy and install software on the remote machine using the full deployment pipeline: download installer, run silent install, verify installation, and track progress. Creates a tracked deployment visible on the Deployments page. Server-side — orchestrated by the server, not the agent directly.

Requires user confirmation before execution. Cortex will summarize the deployment plan (software, version, install path, parallel install status, processes to close) and wait for explicit approval before proceeding.

TouchDesigner specifics: Download URL is auto-constructed from version number. parallel_install is automatically enabled to prevent the installer from removing existing builds. Use the full installer, not the WebInstaller.

Silent flag formats by installer type:

• Inno Setup: /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /DIR="path"
• NSIS: /S /D=path
• MSI: /quiet /norestart INSTALLDIR="path"

reboot_machine

Reboot the remote machine with a 30-second countdown delay. Can be cancelled from the dashboard or via cancel_reboot within the countdown window.

shutdown_machine

Shut down the remote machine with a 30-second countdown delay. The machine will NOT automatically restart.

cancel_reboot

Cancel a pending reboot or shutdown. Must be called within the 30-second countdown window.

security model

tool execution flow

LLM decides to call a tool
  |
  +-- Tier 3: pause for confirmation first
  |     +-- User confirms: continue to the tool-name execution path
  |     +-- User denies: return "denied by user"
  |
  +-- Server-side tools
  |     +-- get_site_logs / get_system_presets query Firestore on the web server
  |     +-- deploy_software creates deployment records and install commands server-side
  |     +-- update_process / add_process / delete_process call process action functions server-side
  |
  +-- Legacy command-mapped tools
  |     +-- Write existing command types such as restart_process or reboot_machine
  |     +-- Agent handles the legacy command and writes completion state
  |
  +-- Firestore mcp_tool_call tools
        +-- Create an mcp_tool_call command in Firestore
        +-- Agent receives and executes the MCP tool
        +-- Agent writes result to completed queue
        +-- API polls for result (1.5s intervals, 30s timeout plus buffer)

command allowlists

run_command enforces an allowlist on the agent side. Even if a command is sent via Firestore, the agent rejects it if the first command isn't in the allowlist. run_powershell has no allow-list — it accepts arbitrary PowerShell, with accountability provided by mandatory audit logging (site events feed + local [MCP-AUDIT] log). run_python enforces its sandbox on the agent side — the LLM cannot override the import gate or restore blocked builtins.

tier 2 blocklists

Tier 2 tools enforce per-tool blocklists to prevent self-inflicted outages:

• manage_process — critical system processes (lsass, winlogon, csrss, etc.) cannot be killed
• registry_operation — SAM, SECURITY, and Cryptography hives are unreachable; only an allowlist of safe key prefixes is permitted
• manage_windows_feature — core Windows features Owlette depends on (NetFx4, WMI-*, PowerShell*) cannot be removed

Agent-executed Tier 2 tools emit structured [MCP-AUDIT] log entries for each invocation. Server-side process config tools use the process mutation audit path with actor cortex:user_<userId>.

agent-side limits

• Subprocess timeout: 25 seconds (default; overridable per-tool where applicable)
• Max output size: 50KB
• Screenshot max size: 10MB