Processes

The Processes API allows you to monitor running applications and perform actions like focusing windows or terminating processes.

macOS Permissions Required

On macOS, using /api/processes/focus or /api/processes/kill requires Accessibility permissions. When you first use these features, macOS may prompt you to grant access. Go to System Settings → Privacy & Security → Accessibility and add Deskctl Bridge to the allowed apps list.

Endpoints

Get Process List (Aggregated)

Returns a list of top memory-consuming processes, aggregated by name. This is useful for general monitoring.

GET /api/processes

Response:

[
  {
    "name": "chrome.exe",
    "count": 12,
    "memory": 4294967296,
    "memory_mb": 4096.0,
    "cpu_time": 120.5
  },
  {
    "name": "Code.exe",
    "count": 5,
    "memory": 2147483648,
    "memory_mb": 2048.0,
    "cpu_time": 45.2
  }
]

Get Process Details (By Name)

Get detailed information about all running instances of a specific process, including PIDs and window titles.

GET /api/processes/{name}

Parameters:

name (path): The name of the process (e.g., notepad.exe).

Response:

[
  {
    "pid": 1234,
    "name": "notepad.exe",
    "title": "Untitled - Notepad",
    "has_window": true,
    "memory": 15482880,
    "cpu": 0.0
  },
  {
    "pid": 5678,
    "name": "notepad.exe",
    "title": "",
    "has_window": false,
    "memory": 4096000,
    "cpu": 0.0
  }
]

Focus Process Window

Attempts to bring the main window of a specific process to the foreground. This is useful for switching context on the remote machine.

POST /api/processes/focus

Body:

{
  "pid": 1234
}

Response:

{
  "status": "success"
}

Platform Requirements

This endpoint relies on the OS window manager. It works best for processes with visible windows (has_window: true).

macOS: Requires Accessibility permissions (see note above).

Kill Process

Terminate one or more processes. You can kill a specific PID or all instances of a process name.

POST /api/processes/kill

macOS Note

On macOS, terminating processes may require Accessibility permissions (see note above).

Body (Kill Single PID):

{
  "pid": 1234
}

Body (Kill All by Name):

{
  "name": "notepad.exe"
}

Response:

{
  "status": "success",
  "count": 1
}

The count field indicates how many processes were terminated.

Launch Process

Start a new application or script on the host machine.

POST /api/processes/launch

Body (Windows Examples):

// Launch Notepad
{
  "path": "notepad.exe"
}

// Launch Spotify (via Protocol)
{
  "path": "cmd",
  "args": ["/C", "start", "spotify:"]
}

Body (macOS Examples):

// Launch TextEdit
{
  "path": "open",
  "args": ["-a", "TextEdit"]
}

// Launch Spotify
{
  "path": "open",
  "args": ["-a", "Spotify"]
}

Response:

{
  "status": "success"
}

Real-Time Process List

For real-time updates, use the WebSocket API. Subscribe to the processes topic and receive process_list events automatically. You can also send kill/launch commands and receive feedback through the same connection.

Example Usage Scenarios

1. Remote Task Manager

Create a dashboard that lists top resource-hogging applications.

Call GET /api/processes to get the top list.
Display them in a table.
If a user clicks "End Task" on "chrome.exe":
Call POST /api/processes/kill with {"name": "chrome.exe"} to close all instances.

2. App Launcher & Switcher

Build a control panel for your favorite apps.

Launch: Use POST /api/processes/launch to start an app.
Switch: Check if the app is running via GET /api/processes/spotify.exe.
If running, iterate through the list to find the instance with has_window: true.
Call POST /api/processes/focus with its PID to bring Spotify to the front.

3. "Boss Mode" / Panic Button

Instantly close distracting apps.

Define a list of apps to close (e.g., games, browsers).
When the button is pressed, cycle through the list.
Call POST /api/processes/kill with {"name": "game.exe"} for each one.

On this page