Skip to content

examples.md

Latest commit

 

History

History
159 lines (107 loc) · 4.69 KB

examples.md

File metadata and controls

159 lines (107 loc) · 4.69 KB
Raw

Examples index

Back to documentation index · start-here.md · guides/

Which example for which problem?

Problem Example
Install broker once; CLI/DSL/REST share capture agent-broker
Headless CI / Docker screenshot headless-virtual
AT-SPI / browser / terminal control demos control-plane
GUI Map Pack (vision-only Wayland) control-plane/gui-map-pack.md
Mirror host desktop to second output host-mirror
Hide window off-screen (relay) host-relay
Develop vdisplay on GNOME Wayland 3-monitor PC dev-workflow
Custom control provider plugin control-plugin

Desktop host — vdisplay-agent (recommended)

agent-broker

Install the broker once; CLI, DSL, REST, and MCP share one capture/runtime via VDISPLAY_AGENT_URL.

cd examples/agent-broker
./run.sh

Or with a persistent agent:

vdisplay-agent serve --port 8765
export VDISPLAY_AGENT_URL=http://127.0.0.1:8765
python3 examples/agent-broker/broker_demo.py

On GNOME Wayland, host screenshots need agent + keeper screencast:

# Terminal 1
export PYTHONPATH=src:packages/vdisplay-agent/src
vdisplay-agent serve --port 8765

# Terminal 2
export VDISPLAY_AGENT_URL=http://127.0.0.1:8765
export PYTHONPATH=src:packages/vdisplay-agent/src
vdisplay agent screencast start --force   # portal → All Screens
vdisplay screenshot -o /tmp/host.png --source DP-1

Full guide: guides/gnome-wayland-screencast.md · Automation: examples/dev-workflow

Files: broker_demo.py, run.sh, README.md

control-plane

Query and interact with UI elements semantically using AT-SPI, terminal, or browser backend providers.

python3 examples/control-plane/control_demo.py

Files: control_demo.py, README.md

Headless (no host display)

headless-virtual

Minimal virtual display inside Docker: start Xvfb, capture screenshot, exit.

cd examples/headless-virtual
docker compose up --build

Files: Dockerfile, docker-compose.yml, run_virtual.py, README.md

ci-agent

Agent-style loop: launch a GUI app on virtual display, capture frame, suitable for CI pipelines.

cd examples/ci-agent
docker compose run --rm ci-agent

Files: Dockerfile, docker-compose.yml, agent.py, README.md

dev-workspace

Development container with the repo mounted as a volume for live code changes.

cd examples/dev-workspace
docker compose run --rm dev

Files: Dockerfile, docker-compose.yml, README.md

Host session (mirror / relay)

Mirror and relay need a running desktop session. On Wayland, prefer vdisplay-agent + ScreenCast for screenshots — Docker X11 forwarding often yields black frames.

host-mirror

Mirror the host primary monitor to a second monitor (when available) and capture a screenshot.

# with broker (Wayland-friendly capture after screencast/start)
vdisplay-agent serve &
export VDISPLAY_AGENT_URL=http://127.0.0.1:8765
cd examples/host-mirror && ./run.sh

# pick monitors explicitly
VD_SOURCE=DP-2 VD_TARGET=HDMI-1 ./run.sh

Output: output/mirror.png

Files: Dockerfile, docker-compose.yml, mirror_demo.py, run.sh, README.md

host-relay

Demonstrate adopting and releasing a window on the host session. Adopted positions persist across CLI calls.

export VDISPLAY_AGENT_URL=http://127.0.0.1:8765   # optional broker

vdisplay windows --apps-only
vdisplay relay adopt-window --app "JetBrains"
vdisplay relay release-window --app "JetBrains"

# Docker demo (X11 sessions; black on Wayland — use ./run-host.sh)
cd examples/host-relay && ./run-host.sh

Files: Dockerfile, docker-compose.yml, relay_demo.py, run.sh, run-host.sh, README.md

Quick reference

Example Mode Docker Host desktop Broker
agent-broker broker No Yes Yes
control-plane control No Yes Optional
headless-virtual virtual Yes No No
ci-agent virtual Yes No No
dev-workspace virtual Yes No No
host-mirror mirror Optional Yes Recommended
host-relay relay Optional Yes Optional