Features System

System Information

Query system status, power information, and control system functions.

System Info

deskbrid system info

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "hostname": "mycomputer",
    "os": "linux",
    "desktop": "gnome",
    "shell": "/bin/bash",
    "uptime": 86400,
    "load_avg": [0.5, 0.3, 0.2]
  }
}

Protocol:

{"action": "system.info"}

System Capabilities

deskbrid system capabilities

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "screenshot": true,
    "ocr": true,
    "clipboard": true,
    "input": true,
    "notifications": true,
    "mpris": true
  }
}

Protocol:

{"action": "system.capabilities"}

System Health

Check system health and diagnose issues:

deskbrid system health

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "healthy": true,
    "checks": [
      {"name": "socket", "status": "ok"},
      {"name": "permissions", "status": "ok"},
      {"name": "backends", "status": "ok"}
    ]
  }
}

Protocol:

{"action": "system.health"}

Power Management

Power Actions

deskbrid system power suspend
deskbrid system power reboot
deskbrid system power shutdown

Protocol:

{"action": "system.power", "action": "suspend"}

Actions:

• suspend - Suspend to RAM
• hibernate - Suspend to disk
• reboot - Reboot system
• shutdown - Power off
• lock - Lock screen

Battery Status

deskbrid system battery

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "percentage": 85,
    "charging": true,
    "time_remaining": 3600
  }
}

Protocol:

{"action": "system.battery"}

Idle Detection

Check how long the system has been idle:

deskbrid system idle

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "idle_ms": 300000,
    "idle": true
  }
}

Protocol:

{"action": "system.idle"}

Inhibit System

Prevent system sleep, screensaver, or session lock:

deskbrid system inhibit suspend --who "backup-script" --why "long-running backup"

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "inhibitor_id": 42
  }
}

Protocol:

{
  "action": "system.inhibit",
  "what": "suspend",
  "who": "backup-script",
  "why": "long-running backup"
}

What to inhibit:

• suspend - Prevent system suspend
• sleep - Prevent system sleep
• idle - Prevent idle activation
• logout - Prevent automatic logout

Modes:

• block - Hard block (default)
• delay - Delay for a time
• transient - Until next session

Release Inhibit

deskbrid system release-inhibit 42

Protocol:

{"action": "system.release_inhibit", "inhibitor_id": 42}

Session Management

List Sessions

deskbrid system sessions

Response:

{
  "type": "response",
  "status": "ok",
  "data": [
    {
      "session_id": "1",
      "username": "user",
      "seat": "seat0",
      "active": true
    }
  ]
}

Lock Session

deskbrid system lock-session
deskbrid system lock-session --session 2

Protocol:

{"action": "system.lock_session"}

Switch User

deskbrid system switch-user alice

Protocol:

{"action": "system.switch_user", "username": "alice"}

Privilege Escalation

Check Auth

Check if an action requires authorization:

deskbrid system check-auth system.power

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "authorized": false,
    "action_id": "system.power"
  }
}

Elevate Privileges

Request privilege elevation:

deskbrid system elevate system.power --reason "User requested shutdown"

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "authorized": true
  }
}

Confinement Status

Check if running in a sandbox (Flatpak, Snap):

deskbrid system confinement

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "confined": true,
    "type": "flatpak",
    "sandbox": true
  }
}

Remediate Issues

Fix common problems:

deskbrid system remediate --check socket
deskbrid system remediate --check permissions --apply

Protocol:

{"action": "system.remediate", "check": "socket", "apply": true}

Normalize Coordinates

Convert pixel coordinates between monitor layouts:

deskbrid system normalize-coords --x 1000 --y 500

Protocol:

{"action": "system.normalize_coords", "x": 1000, "y": 500}

Python Example

from deskbrid import Deskbrid

client = Deskbrid()

# Get system status
info = client.info()
print(f"Desktop: {info.desktop}, Uptime: {info.uptime}s")

# Check battery
battery = client.system_battery()
print(f"Battery: {battery['percentage']}%")

# Prevent sleep during long operation
inhibit = client.inhibit_system("suspend", who="backup", why="backup running")
try:
    # ... long running task ...
    pass
finally:
    client.release_inhibit(inhibit["inhibitor_id"])