<!--
hoody-display Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T19:02:42.986Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 8076

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-display Subskill

## Overview

**hoody-display** provides fully embeddable, multiplayer desktop environments accessible via URL. It exposes a virtual display (X11-based) through a REST API, enabling programmatic control of GUI applications, screenshots, window management, and input simulation.

### When to Use

- **GUI automation**: Control desktop applications via API (click, type, drag)
- **Visual monitoring**: Capture screenshots/thumbnails of running applications
- **Window management**: List, focus, move, resize, and close windows
- **Clipboard operations**: Read/write clipboard content programmatically
- **Embeddable desktops**: Serve a web-based display client accessible via any browser

### Philosophy Alignment

hoody-display embodies the Hoody philosophy of **fully embeddable, multiplayer desktop environments**. Each display instance is:
- **URL-accessible**: No VNC client required — the HTML5 client loads directly
- **Multiplayer**: Multiple agents/users can interact with the same display
- **Isolated**: Each container gets its own display instance
- **API-first**: Every interaction is a REST call, enabling AI agent integration

### Service URL Pattern

```
https://{projectId}-{containerId}-display-{serviceId}.{node}.containers.hoody.icu
```

All paths below are relative to this base URL. Use **exactly** the paths from the endpoint inventory.

---

## Common Workflows

### 1. Health Check & Service Discovery

Verify the display service is running and gather instance information.

```
# Health check (unauthenticated)
curl -s "https://{BASE_URL}/api/v1/display/health"

# Get display info (includes available screenshots)
curl -s "https://{BASE_URL}/api/v1/display/info"

# List all available screenshots
curl -s "https://{BASE_URL}/api/v1/display/screenshots"
```

**Health response structure:**
```
{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00Z",
  "uptime": 3600,
  "version": "1.0.0",
  "service": "hoody-display",
  "containerId": "abc123",
  "projectId": "proj456",
  "node": "us-east-1"
}
```

### 2. Screenshot Capture & Retrieval

Capture the current display state for monitoring or AI vision analysis.

```
# Capture fresh screenshot (returns image file)
curl -s "https://{BASE_URL}/api/v1/display/screenshot" -o screenshot.png

# Capture screenshot metadata only (no image download)
curl -s "https://{BASE_URL}/api/v1/display/screenshot/info"

# Get latest previously captured screenshot
curl -s "https://{BASE_URL}/api/v1/display/screenshot/last" -o last_screenshot.png

# Get metadata for latest screenshot
curl -s "https://{BASE_URL}/api/v1/display/screenshot/last/info"

# Retrieve screenshot by timestamp
curl -s "https://{BASE_URL}/api/v1/display/screenshot/{timestamp}" -o specific.png
```

**Screenshot metadata response:**
```
{
  "timestamp": 1705312200,
  "width": 1920,
  "height": 1080,
  "format": "png",
  "size": 245760
}
```

### 3. Thumbnail Capture

Thumbnails are 320×180 scaled versions — faster to transfer for monitoring loops.

```
# Capture fresh thumbnail
curl -s "https://{BASE_URL}/api/v1/display/thumbnail" -o thumb.png

# Get latest thumbnail
curl -s "https://{BASE_URL}/api/v1/display/thumbnail/last" -o last_thumb.png

# Get thumbnail by timestamp
curl -s "https://{BASE_URL}/api/v1/display/thumbnail/{timestamp}" -o specific_thumb.png
```

### 4. Mouse Input

Simulate mouse interactions on the display.

```
# Move mouse to absolute coordinates
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/move" \
  -H "Content-Type: application/json" \
  -d '{
  "x": 500,
  "y": 300
}'

# Move mouse relative to current position
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/move-relative" \
  -H "Content-Type: application/json" \
  -d '{
  "x": 50,
  "y": -25
}'

# Single click at current position
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/click"

# Double click
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/double-click"

# Mouse button down (for drag operations)
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/down"

# Mouse button up
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/up"

# Scroll (direction: "up" or "down")
curl -s -X POST "https://{BASE_URL}/api/v1/display/mouse/scroll" \
  -H "Content-Type: application/json" \
  -d '{
  "direction": "down"
}'

# Get current mouse location
curl -s "https://{BASE_URL}/api/v1/display/mouse/location"
```

**Mouse location response:**
```
{
  "x": 500,
  "y": 300
}
```

### 5. Keyboard Input

Type text and send key combinations.

```
# Type text string
curl -s -X POST "https://{BASE_URL}/api/v1/display/keyboard/type" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello, World!"
}'

# Send key combination (array of key combos)
curl -s -X POST "https://{BASE_URL}/api/v1/display/keyboard/key" \
  -H "Content-Type: application/json" \
  -d '{
  "keys": ["ctrl+c"]
}'

# Press key down (X11 keysym)
curl -s -X POST "https://{BASE_URL}/api/v1/display/keyboard/key-down" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "Shift_L"
}'

# Release key
curl -s -X POST "https://{BASE_URL}/api/v1/display/keyboard/key-up" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "Shift_L"
}'
```

### 6. Clipboard Operations

Read and write clipboard content.

```
# Get current clipboard content
curl -s "https://{BASE_URL}/api/v1/display/clipboard"

# Set clipboard content
curl -s -X POST "https://{BASE_URL}/api/v1/display/clipboard" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Clipboard content to set"
}'
```

### 7. Window Management

List, inspect, and control windows on the display.

```
# List all windows
curl -s "https://{BASE_URL}/api/v1/display/windows"

# Get active (focused) window
curl -s "https://{BASE_URL}/api/v1/display/window/active"

# Get window properties
curl -s "https://{BASE_URL}/api/v1/display/window/{windowId}/properties"

# Get window geometry
curl -s "https://{BASE_URL}/api/v1/display/window/{windowId}/geometry"

# Get window name
curl -s "https://{BASE_URL}/api/v1/display/window/{windowId}/name"

# Focus a window
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/focus" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001"
}'

# Move a window
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/move" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001",
  "x": 100,
  "y": 100
}'

# Resize a window
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/resize" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001",
  "width": 800,
  "height": 600
}'

# Close a window
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/close" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001"
}'

# Minimize a window
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/minimize" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001"
}'

# Raise a window (bring to front)
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/raise" \
  -H "Content-Type: application/json" \
  -d '{
  "windowId": "0x03400001"
}'

# Search for windows
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/search" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Firefox"
}'
```

### 8. Display Client Access

Access the HTML5 web-based display client directly in a browser.

```
# Open the display client (returns HTML)
curl -s "https://{BASE_URL}/api/v1/display/"
```

Navigate to `https://{BASE_URL}/api/v1/display/` in a browser for the full interactive desktop experience.

---

## Advanced Operations

### 1. Click-at-Position Workflow

Combine screenshot analysis with precise clicking for GUI automation.

```
# Step 1: Capture screenshot to identify UI elements
curl -s "https://{BASE_URL}/api/v1/display/screenshot/info"

# Step 2: Click at specific coordinates
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/click-at" \
  -H "Content-Type: application/json" \
  -d '{
  "x": 450,
  "y": 200
}'

# Step 3: Verify by taking another screenshot
curl -s "https://{BASE_URL}/api/v1/display/screenshot/info"
```

### 2. Type-at-Position Workflow

Click a text field and type into it.

```
# Step 1: Click on the target input field
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/type-at" \
  -H "Content-Type: application/json" \
  -d '{
  "x": 300,
  "y": 400,
  "text": "user@example.com"
}'

# Step 2: Verify with screenshot
curl -s "https://{BASE_URL}/api/v1/display/screenshot/last/info"
```

### 3. Drag Operation

Perform drag-and-drop between two points.

```
# Drag from point A to point B
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/drag" \
  -H "Content-Type: application/json" \
  -d '{
  "startX": 100,
  "startY": 200,
  "endX": 500,
  "endY": 400
}'
```

### 4. Batch Input Operations

Send multiple input actions in a single request for efficiency.

```
# Batch multiple input actions
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/batch" \
  -H "Content-Type: application/json" \
  -d '{
  "actions": [
    {"type": "move", "x": 100, "y": 100},
    {"type": "click"},
    {"type": "type", "text": "Hello"}
  ]
}'
```

### 5. Display Geometry & Input Reset

Get display dimensions and reset input state.

```
# Get display geometry
curl -s "https://{BASE_URL}/api/v1/display/input/display-geometry"

# Reset input state (release all keys/buttons)
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/reset"
```

### 6. Wait for State

Wait for a specific condition before proceeding.

```
# Wait for a condition (e.g., window to appear)
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/wait" \
  -H "Content-Type: application/json" \
  -d '{
  "condition": "window_exists",
  "value": "Firefox",
  "timeout": 10000
}'
```

### 7. Select Text

Select text at a specific region.

```
# Select text in a region
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/select" \
  -H "Content-Type: application/json" \
  -d '{
  "startX": 100,
  "startY": 200,
  "endX": 400,
  "endY": 220
}'
```

### 8. Compound Action Endpoint

Execute a single high-level action.

```
# Execute a compound action
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/act" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "click_and_type",
  "x": 300,
  "y": 400,
  "text": "search query"
}'
```

### Error Recovery Patterns

**Input state stuck (keys held down):**
```
# Reset all input state
curl -s -X POST "https://{BASE_URL}/api/v1/display/input/reset"

# Verify mouse is responsive
curl -s "https://{BASE_URL}/api/v1/display/mouse/location"
```

**Window not found after launch:**
```
# Search for the window by name
curl -s -X POST "https://{BASE_URL}/api/v1/display/window/search" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Application Name"
}'

# List all windows to debug
curl -s "https://{BASE_URL}/api/v1/display/windows"
```

### Performance Considerations

- **Use thumbnails** (320×180) for monitoring loops instead of full screenshots
- **Use `/screenshot/last`** when you don't need a fresh capture
- **Use batch operations** to reduce HTTP round-trips
- **Use `/screenshot/info`** when you only need metadata (dimensions, timestamp)
- **Set appropriate timeouts** — display operations can take 1-5 seconds

---

## Quick Reference

### Most Common Endpoints

| Operation | Method | Path |
|-----------|--------|------|
| Health check | GET | `/api/v1/display/health` |
| Screenshot | GET | `/api/v1/display/screenshot` |
| Latest screenshot | GET | `/api/v1/display/screenshot/last` |
| Thumbnail | GET | `/api/v1/display/thumbnail` |
| Mouse click | POST | `/api/v1/display/mouse/click` |
| Mouse move | POST | `/api/v1/display/mouse/move` |
| Type text | POST | `/api/v1/display/keyboard/type` |
| Send key | POST | `/api/v1/display/keyboard/key` |
| List windows | GET | `/api/v1/display/windows` |
| Focus window | POST | `/api/v1/display/window/focus` |
| Get clipboard | GET | `/api/v1/display/clipboard` |
| Set clipboard | POST | `/api/v1/display/clipboard` |
| Display client | GET | `/api/v1/display/` |
| Display info | GET | `/api/v1/display/info` |

### Essential Parameters

| Endpoint | Required Fields | Type |
|----------|----------------|------|
| `mouse/move` | `x`, `y` | integer |
| `mouse/move-relative` | `x`, `y` | integer |
| `mouse/scroll` | `direction` | string ("up"/"down") |
| `keyboard/type` | `text` | string |
| `keyboard/key` | `keys` | array of strings |
| `keyboard/key-down` | `key` | string (X11 keysym) |
| `keyboard/key-up` | `key` | string |
| `clipboard` (POST) | `text` | string |
| `window/focus` | `windowId` | string |
| `window/move` | `windowId`, `x`, `y` | string, integer, integer |
| `screenshot/{timestamp}` | `timestamp` | string (query param) |
| `thumbnail/{timestamp}` | `timestamp` | string (query param) |

### Typical Response Formats

**Health/info endpoints** return JSON with service metadata.

**Screenshot/thumbnail endpoints** return image binary (PNG) or JSON metadata.

**Window list** returns array of window objects with IDs and names.

**Mouse location** returns `{ "x": int, "y": int }`.

**Input action endpoints** return success/failure status.

### Display Client URL

Open in browser for interactive desktop:
```
https://{projectId}-{containerId}-display-{serviceId}.{node}.containers.hoody.icu/api/v1/display/
```