Features System

System Information

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

System Info

deskbrid system info

Response:

{
  "type": "response",
  "status": "ok",
  "data": {
    "desktop": "gnome",
    "desktop_version": "45.0",
    "compositor": "gnome-shell",
    "session_type": "wayland",
    "monitors": [
      {"id": 0, "name": "DP-1", "width": 1920, "height": 1080, "scale": 1.0, "primary": true}
    ],
    "workspace_count": 4,
    "current_workspace": 0,
    "idle_seconds": 300
  }
}

Protocol:

{"type": "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:

{"type": "system.capabilities"}

Power Management

Power Actions

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

Protocol:

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

Actions:

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

Idle Detection

Check how long the system has been idle:

deskbrid system idle

Response:

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

Protocol:

{"type": "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:

{
  "type": "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

Release Inhibit

deskbrid system release-inhibit 42

Protocol:

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

Session Management

List Sessions

deskbrid system sessions

Response:

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

Protocol:

{"type": "system.sessions"}

Lock Session

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

Protocol:

{"type": "system.lock_session"}

Switch User

deskbrid system switch-user alice

Protocol:

{"type": "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
  }
}

Python Example

from deskbrid import Deskbrid

client = Deskbrid()

# Get system status
info = client.info()
print(f"Desktop: {info.desktop}, Session: {info.session_type}")

# Inhibit 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"])