API Overview

Introduction to DWN's WebSocket API

On this page

Introduction

DWN provides a WebSocket API for full programmatic control of the window manager. This enables:

  • Test Automation - Automated UI testing and scripting
  • Custom Hotkeys - Build custom keyboard shortcuts
  • Remote Control - Control DWN from other machines or devices
  • Integration - Connect DWN to other applications
  • Accessibility - Build alternative input methods

Enabling the API

The API is disabled by default. Enable it in ~/.config/dwn/config:

[api]
enabled = true
port = 8777

Restart DWN for changes to take effect.

Security Note: The API listens on localhost only by default. Be cautious when exposing to network.

Connecting

Connect via WebSocket to ws://localhost:8777/ws (or your configured port). The /ws path is required.

Testing with wscat

# Install wscat
npm install -g wscat

# Connect to DWN
wscat -c ws://localhost:8777/ws

# Send a command
> {"command": "get_clients"}
< {"status": "ok", "clients": [...]}

Testing with websocat

# Install websocat
cargo install websocat

# Connect and send command
echo '{"command": "get_clients"}' | websocat ws://localhost:8777/ws

Protocol

Request Format

All requests are JSON objects with a command field:

{
    "command": "command_name",
    "param1": "value1",
    "param2": "value2"
}

Response Format

Responses include a status field:

// Success
{
    "status": "ok",
    "data": {...}
}

// Error
{
    "status": "error",
    "message": "Error description"
}

Command Categories

Category Commands
Clients get_clients, find_clients, get_focused_client, focus_client, focus_next, focus_prev, focus_master, close_client, kill_client, move_client, resize_client, minimize_client, restore_client, maximize_client, fullscreen_client, float_client, raise_client, lower_client, snap_client
Workspaces get_workspaces, switch_workspace, switch_workspace_next, switch_workspace_prev, move_client_to_workspace
Layout set_layout, cycle_layout, set_master_ratio, adjust_master_ratio, set_master_count, adjust_master_count
Keyboard key_press, key_release, key_tap, key_type, get_keybindings
Mouse mouse_move, mouse_move_relative, mouse_click, mouse_press, mouse_release, mouse_scroll, get_mouse_position
Screenshot screenshot
OCR ocr
System get_status, get_screen_info, run_command, show_desktop, get_config, reload_config
Notifications notify, close_notification, get_notifications
System Tray get_battery_state, get_audio_state, set_audio_volume, toggle_audio_mute, get_wifi_state
Panels get_panel_state, show_panel, hide_panel, toggle_panel
AI ai_is_available, ai_command, exa_is_available, exa_search
News get_news, news_next, news_prev, news_open
Demo/Tutorial start_demo, stop_demo, get_demo_state, start_tutorial, stop_tutorial, get_tutorial_state
Events subscribe, unsubscribe, list_events
Fade Effects get_fade_settings, set_fade_speed, set_fade_intensity

Quick Start

List Clients

// Request
{"command": "get_clients"}

// Response
{
    "status": "ok",
    "clients": [
        {
            "window": 12345678,
            "title": "Firefox",
            "class": "firefox",
            "workspace": 0,
            "x": 0, "y": 32,
            "width": 960, "height": 540,
            "focused": true,
            "floating": false,
            "fullscreen": false,
            "maximized": false,
            "minimized": false
        }
    ]
}

Focus a Client

{"command": "focus_client", "window": 12345678}

Switch Workspace

{"command": "switch_workspace", "workspace": 2}

Type Text

{"command": "key_type", "text": "Hello, World!"}

Take Screenshot

// Request
{"command": "screenshot", "mode": "fullscreen"}

// Response
{
    "status": "ok",
    "format": "png",
    "encoding": "base64",
    "width": 1920,
    "height": 1080,
    "data": "iVBORw0KGgo..."
}

Client Libraries

Python Client

A Python client is included in the examples/ directory:

from dwn_api_client import DWNClient

# Connect
client = DWNClient()
client.connect()

# List clients
clients = client.get_clients()

# Focus a client
client.focus_client(clients[0]['window'])

# Take screenshot
result = client.screenshot('fullscreen')
with open('screenshot.png', 'wb') as f:
    f.write(base64.b64decode(result['data']))

# Disconnect
client.disconnect()

JavaScript (Browser)

const ws = new WebSocket('ws://localhost:8777/ws');

ws.onopen = () => {
    ws.send(JSON.stringify({command: 'get_clients'}));
};

ws.onmessage = (event) => {
    const response = JSON.parse(event.data);
    console.log(response);
};

Web Remote

A web-based remote control interface is included at examples/web_remote.html. Open it in a browser to control DWN graphically.

Next Steps