screen-relay 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/Makefile +165 -0
- package/README.md +113 -2
- package/THIRD-PARTY-NOTICES.md +75 -0
- package/dist/cli/client.d.ts +28 -0
- package/dist/cli/commands.d.ts +52 -0
- package/dist/cli/config.d.ts +32 -0
- package/dist/cli/format.d.ts +15 -0
- package/dist/cli/help.d.ts +5 -0
- package/dist/cli/host/common.d.ts +23 -0
- package/dist/cli/host/doctor.d.ts +2 -0
- package/dist/cli/host/packages.d.ts +13 -0
- package/dist/cli/host/session_commands.d.ts +8 -0
- package/dist/cli/host/setup.d.ts +22 -0
- package/dist/cli/host/state.d.ts +23 -0
- package/dist/cli/host/supervisor.d.ts +91 -0
- package/dist/cli/host/watcher.d.ts +4 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/mode.d.ts +14 -0
- package/dist/cli/output.d.ts +24 -0
- package/dist/cli/parser.d.ts +6 -0
- package/dist/cli/relay.mjs +12247 -0
- package/dist/cli/skills.d.ts +21 -0
- package/dist/cli/theme.d.ts +14 -0
- package/dist/protocol/errors.d.ts +155 -0
- package/dist/protocol/index.d.ts +119 -0
- package/dist/protocol/index.js +418 -0
- package/dist/sdk/index.d.ts +77 -0
- package/dist/sdk/index.js +724 -0
- package/dist/viewer/index.html +96 -0
- package/dist/viewer/viewer.js +1052 -0
- package/package.json +50 -4
- package/packages.tsv +38 -0
- package/skills/core/SKILL.md +169 -0
- package/skills/core/references/cli.md +119 -0
- package/skills/core/references/config.md +48 -0
- package/skills/core/references/macos.md +50 -0
- package/skills/core/references/sdk.md +69 -0
- package/skills/core/references/troubleshooting.md +33 -0
- package/skills/core/references/wayland.md +47 -0
- package/skills/screen-relay/SKILL.md +24 -0
- package/skills/vercel-sandbox/SKILL.md +68 -0
- package/src/engine/backends/linux/keycodes.hpp +35 -0
- package/src/engine/backends/linux/wayland/capture.cpp +298 -0
- package/src/engine/backends/linux/wayland/input.cpp +559 -0
- package/src/engine/backends/linux/wayland/keymap.cpp +118 -0
- package/src/engine/backends/linux/wayland/keymap.hpp +54 -0
- package/src/engine/backends/linux/wayland/protocols/virtual-keyboard-unstable-v1.xml +112 -0
- package/src/engine/backends/linux/wayland/protocols/wlr-screencopy-unstable-v1.xml +234 -0
- package/src/engine/backends/linux/wayland/protocols/wlr-virtual-pointer-unstable-v1.xml +152 -0
- package/src/engine/backends/linux/wayland/wayland.cpp +166 -0
- package/src/engine/backends/linux/wayland/wayland.hpp +60 -0
- package/src/engine/backends/linux/x11/capture.cpp +206 -0
- package/src/engine/backends/linux/x11/input.cpp +266 -0
- package/src/engine/backends/macos/capture.mm +367 -0
- package/src/engine/backends/macos/display.hpp +20 -0
- package/src/engine/backends/macos/display.mm +84 -0
- package/src/engine/backends/macos/input.mm +287 -0
- package/src/engine/backends/macos/keys.hpp +34 -0
- package/src/engine/backends/windows/capture.cpp +393 -0
- package/src/engine/backends/windows/input.cpp +274 -0
- package/src/engine/backends/windows/output.cpp +65 -0
- package/src/engine/backends/windows/output.hpp +26 -0
- package/src/engine/core/capture-bucket.hpp +40 -0
- package/src/engine/core/capture-source.hpp +59 -0
- package/src/engine/core/capture.cpp +565 -0
- package/src/engine/core/capture.hpp +58 -0
- package/src/engine/core/color.cpp +176 -0
- package/src/engine/core/color.hpp +16 -0
- package/src/engine/core/cpu-budget.hpp +196 -0
- package/src/engine/core/flow.hpp +317 -0
- package/src/engine/core/input.cpp +98 -0
- package/src/engine/core/input.hpp +115 -0
- package/src/engine/core/wait.cpp +125 -0
- package/src/engine/core/wait.hpp +41 -0
- package/src/engine/server/backend.cpp +65 -0
- package/src/engine/server/backend.hpp +18 -0
- package/src/engine/server/config.cpp +257 -0
- package/src/engine/server/config.hpp +24 -0
- package/src/engine/server/main.cpp +82 -0
- package/src/engine/server/metrics.cpp +47 -0
- package/src/engine/server/metrics.hpp +10 -0
- package/src/engine/server/screenshot.cpp +108 -0
- package/src/engine/server/screenshot.hpp +31 -0
- package/src/engine/server/server.cpp +531 -0
- package/src/engine/server/server.hpp +88 -0
- package/src/engine/server/wire.cpp +65 -0
- package/src/engine/server/wire.hpp +27 -0
package/package.json
CHANGED
|
@@ -1,6 +1,52 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "screen-relay",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Stream a desktop to a browser and control it from a CLI and a Node SDK.",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/vercel-labs/screen-relay.git"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"bin": {
|
|
12
|
+
"screen-relay": "dist/cli/relay.mjs"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"skills",
|
|
17
|
+
"packages.tsv",
|
|
18
|
+
"Makefile",
|
|
19
|
+
"src/engine",
|
|
20
|
+
"THIRD-PARTY-NOTICES.md"
|
|
21
|
+
],
|
|
22
|
+
"exports": {
|
|
23
|
+
".": {
|
|
24
|
+
"types": "./dist/sdk/index.d.ts",
|
|
25
|
+
"import": "./dist/sdk/index.js"
|
|
26
|
+
},
|
|
27
|
+
"./protocol": {
|
|
28
|
+
"types": "./dist/protocol/index.d.ts",
|
|
29
|
+
"import": "./dist/protocol/index.js"
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=22"
|
|
34
|
+
},
|
|
35
|
+
"scripts": {
|
|
36
|
+
"build": "node build.mjs",
|
|
37
|
+
"test": "npm run build && node --test tests/unit/*.test.mjs",
|
|
38
|
+
"test:e2e": "node tests/e2e/viewer.mjs",
|
|
39
|
+
"typecheck": "tsc -p ."
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@types/node": "26.6.6",
|
|
43
|
+
"agent-browser": "0.41.2",
|
|
44
|
+
"esbuild": "0.28.2",
|
|
45
|
+
"typescript": "7.0.2"
|
|
46
|
+
},
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"@clack/prompts": "1.9.0",
|
|
49
|
+
"@vercel/detect-agent": "1.2.7",
|
|
50
|
+
"yaml": "2.9.1"
|
|
51
|
+
}
|
|
52
|
+
}
|
package/packages.tsv
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
core compiler build-essential gcc-c++ make base-devel build-base
|
|
2
|
+
core pkg-config pkg-config pkgconf-pkg-config pkgconf pkgconf
|
|
3
|
+
core setpriv util-linux util-linux util-linux setpriv
|
|
4
|
+
core x264-dev libx264-dev x264-devel x264 x264-dev
|
|
5
|
+
core libwebsockets-dev libwebsockets-dev libwebsockets-devel libwebsockets libwebsockets-dev openssl-dev
|
|
6
|
+
core zlib-dev zlib1g-dev zlib-ng-compat-devel zlib zlib-dev
|
|
7
|
+
core linux-headers - - - linux-headers
|
|
8
|
+
x11 libx11-dev libx11-dev libX11-devel libx11 libx11-dev
|
|
9
|
+
x11 libxext-dev libxext-dev libXext-devel libxext libxext-dev
|
|
10
|
+
x11 libxdamage-dev libxdamage-dev libXdamage-devel libxdamage libxdamage-dev
|
|
11
|
+
x11 libxfixes-dev libxfixes-dev libXfixes-devel libxfixes libxfixes-dev
|
|
12
|
+
x11 libxtst-dev libxtst-dev libXtst-devel libxtst libxtst-dev
|
|
13
|
+
x11 Xvfb xvfb xorg-x11-server-Xvfb xorg-server-xvfb xvfb
|
|
14
|
+
x11 xauth xauth xorg-x11-xauth xorg-xauth xauth
|
|
15
|
+
x11 xprop x11-utils xprop xorg-xprop xprop
|
|
16
|
+
x11 xwininfo x11-utils xwininfo xorg-xwininfo xwininfo
|
|
17
|
+
x11 xdpyinfo x11-utils xdpyinfo xorg-xdpyinfo xdpyinfo
|
|
18
|
+
x11 setxkbmap x11-xkb-utils setxkbmap xorg-setxkbmap setxkbmap
|
|
19
|
+
xfce dbus-run-session dbus dbus-daemon dbus dbus
|
|
20
|
+
xfce dbus-x11 dbus-x11 dbus-x11 dbus dbus-x11
|
|
21
|
+
xfce at-spi2-core at-spi2-core at-spi2-core at-spi2-core at-spi2-core
|
|
22
|
+
xfce xfce4-session xfce4-session xfce4-session xfce4-session xfce4-session
|
|
23
|
+
xfce xfwm4 xfwm4 xfwm4 xfwm4 xfwm4
|
|
24
|
+
xfce xfce4-panel xfce4-panel xfce4-panel xfce4-panel xfce4-panel
|
|
25
|
+
xfce xfdesktop xfdesktop4 xfdesktop xfdesktop xfdesktop
|
|
26
|
+
xfce xfce4-settings xfce4-settings xfce4-settings xfce4-settings xfce4-settings
|
|
27
|
+
xfce thunar thunar Thunar thunar thunar
|
|
28
|
+
xfce xfce4-terminal xfce4-terminal xfce4-terminal xfce4-terminal xfce4-terminal
|
|
29
|
+
xfce fonts-dejavu fonts-dejavu-core dejavu-sans-fonts ttf-dejavu font-dejavu
|
|
30
|
+
xfce librsvg librsvg2-common librsvg2 librsvg librsvg
|
|
31
|
+
xfce glycin-loaders glycin-loaders glycin-loaders glycin glycin-loaders-all
|
|
32
|
+
xfce gdk-pixbuf-bin libgdk-pixbuf2.0-bin gdk-pixbuf2-devel gdk-pixbuf2 gdk-pixbuf
|
|
33
|
+
wayland wayland-dev libwayland-dev wayland-devel wayland wayland-protocols wayland-dev
|
|
34
|
+
wayland wayland-scanner libwayland-bin wayland-devel wayland wayland-dev
|
|
35
|
+
wayland xkbcommon-dev libxkbcommon-dev libxkbcommon-devel libxkbcommon libxkbcommon-dev
|
|
36
|
+
wayland sway sway sway sway sway
|
|
37
|
+
wayland Xwayland xwayland xorg-x11-server-Xwayland xorg-xwayland xwayland
|
|
38
|
+
wayland foot foot foot foot foot
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: core
|
|
3
|
+
description: Control a screen-relay desktop from an agent using screenshots and input commands.
|
|
4
|
+
allowed-tools: Bash(screen-relay:*)
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# screen-relay core workflow
|
|
8
|
+
|
|
9
|
+
screen-relay streams a desktop to a browser viewer and gives you CLI control. Run it on the Linux or macOS machine that shows the desktop. Node 22 or newer is required.
|
|
10
|
+
|
|
11
|
+
## Set up
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install -g screen-relay
|
|
15
|
+
screen-relay install --yes
|
|
16
|
+
screen-relay up -d
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- `npm install -g screen-relay` installs the CLI, the Node SDK, the viewer, the agent skills and the engine source. It runs no install script and installs no system packages. Client commands work at once with `--url` and a token file.
|
|
20
|
+
- `screen-relay install --yes` installs the system packages and builds the engine. On a fresh machine it can take several minutes. Run it with a long command timeout or in the background, and wait for it to exit before `up`. It is safe to repeat. With `--json` it prints nothing until it finishes. A failed step returns one JSON error with the command and the end of its output.
|
|
21
|
+
- `up` runs setup when the machine is not set up. You have no terminal, so pass `--yes`.
|
|
22
|
+
- `install --backend wayland --yes` sets up sway, XWayland and foot. `--desktop none` skips the XFCE packages on x11. `up -d --yes` runs setup and starts the session in one command.
|
|
23
|
+
- After an upgrade, the next `up` rebuilds the engine. That needs no `sudo`.
|
|
24
|
+
- Linux: automatic setup supports Debian, Ubuntu, Fedora, Arch Linux and Alpine on x64 and arm64. It needs root or passwordless `sudo`. On another distribution, install the build tools and libraries yourself, then run `screen-relay install`.
|
|
25
|
+
- macOS: setup needs Homebrew and the Xcode Command Line Tools. See [macOS](references/macos.md).
|
|
26
|
+
|
|
27
|
+
## Pick a backend
|
|
28
|
+
|
|
29
|
+
| Platform | Backend | Start |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| macOS | `macos`: streams the logged-in user's display. Starts no virtual display or desktop. | `screen-relay up -d` |
|
|
32
|
+
| Linux | `x11`: a virtual display with XFCE. | `screen-relay up -d` |
|
|
33
|
+
| Linux | `wayland`: a headless sway desktop with foot. | `screen-relay up -d --backend wayland` |
|
|
34
|
+
| Linux | Attach to a compositor you already run. | `screen-relay up -d --backend wayland --display "$WAYLAND_DISPLAY"` |
|
|
35
|
+
|
|
36
|
+
- On Linux, `up` uses `x11` when the engine has it, else `wayland`.
|
|
37
|
+
- Precedence: `--backend`, then `SCREEN_RELAY_BACKEND`, then the config `backend` key, then the default above.
|
|
38
|
+
- Set up a backend before you use it, for example `screen-relay install --backend wayland --yes`.
|
|
39
|
+
- To switch backends, run `screen-relay down` first. While a session with that name runs, `up` fails with `already_running`.
|
|
40
|
+
- To attach, run the command from a terminal inside that session. `--display` takes an X display such as `:0` on x11, or a Wayland socket such as `wayland-1` on wayland. A `--display` without a colon selects wayland. Attach mode uses the display's size and starts no desktop. Compositor setup and limits: [Wayland](references/wayland.md).
|
|
41
|
+
|
|
42
|
+
## Where commands run
|
|
43
|
+
|
|
44
|
+
- VM commands (`install`, `up`, `down`, `logs`, `run`, `doctor`) run on the Linux or macOS machine that shows the desktop. `up`, `down` and `run` fail with `unsupported_platform` elsewhere.
|
|
45
|
+
- Client commands (`status`, `screenshot`, `click`, `move`, `scroll`, `key`, `type`, `input`) reach the engine through the local session, or from another machine with `--url` and a token file (`--token-file` or `SCREEN_RELAY_TOKEN_FILE`). See [Client target](references/cli.md#client-target).
|
|
46
|
+
- `skills` and `help` work anywhere and never contact an engine.
|
|
47
|
+
- A script can use the Node SDK instead of the CLI. See [Node SDK](references/sdk.md).
|
|
48
|
+
|
|
49
|
+
## Start a session
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
screen-relay up -d
|
|
53
|
+
screen-relay status --json
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- `up -d` returns when the display, desktop and engine are ready. Piped, it prints the viewer URL, with the `#token=` fragment when the session has a token. Treat that URL as a secret.
|
|
57
|
+
- `status --json` prints `{"session": {...}}`. Read `session.state` (`starting`, `ready`, `stopped`, `failed`), `session.running`, `session.url` and `session.display`.
|
|
58
|
+
- An existing session exits 0 in any state. A missing session exits 1 with `not_running`.
|
|
59
|
+
|
|
60
|
+
## Control loop
|
|
61
|
+
|
|
62
|
+
Take a screenshot, decide from the image, act, then take another screenshot to verify. This run opens a terminal, types, and checks the result. On Wayland, use `foot` in place of `xfce4-terminal`. On macOS, use `screen-relay run -- open -a Terminal`.
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
screen-relay up -d
|
|
66
|
+
screen-relay run -- xfce4-terminal
|
|
67
|
+
sleep 1
|
|
68
|
+
screen-relay screenshot /tmp/relay.png
|
|
69
|
+
screen-relay click 0.5 0.5
|
|
70
|
+
screen-relay type "echo hello"
|
|
71
|
+
screen-relay key Enter
|
|
72
|
+
screen-relay screenshot /tmp/relay-after.png
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- `run` returns the app's pid at once. The window appears a moment later, so poll `screenshot` until you see it. Read app output with `screen-relay logs apps`. `screen-relay down` stops apps.
|
|
76
|
+
- A saved screenshot means the engine captured the frame. Applied input means the engine applied the events. Neither means the app reacted, so check the next screenshot.
|
|
77
|
+
- Click a window before you type into it. A click also moves the pointer.
|
|
78
|
+
- Read values by looking at the screenshot. `--json` reports geometry and sizes, not text:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{"screenshot":{"path":"/tmp/relay.png","width":1920,"height":1080,"bytes":48213},"outcome":"saved"}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Scroll with `screen-relay scroll 0.5 0.5 --dy 5`, then take a screenshot. For `--dx` and `--dy`, see [CLI](references/cli.md#client-commands).
|
|
85
|
+
|
|
86
|
+
## Coordinates
|
|
87
|
+
|
|
88
|
+
Coordinates are fractions from `0` to `1`, measured from the top-left.
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
x = pixel_x / image_width
|
|
92
|
+
y = pixel_y / image_height
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
For a 1920x1080 screenshot, pixel `480,810` is `screen-relay click 0.25 0.75`, and the center is `screen-relay click 0.5 0.5`. Get the image size from `screen-relay screenshot file.png --json`, or from the image.
|
|
96
|
+
|
|
97
|
+
## type versus key
|
|
98
|
+
|
|
99
|
+
- `screen-relay type <text>` sends layout-neutral text events, one per Unicode scalar value. The remote keyboard layout decides each character, so accents, symbols and non-US layouts work. Use it for text.
|
|
100
|
+
- `screen-relay key <combo>...` sends physical key combinations, in order, such as `ctrl+l`, `alt+Tab`, `cmd+shift+t` and `Enter`. Use it for shortcuts, arrows, function keys and Escape. Modifiers are `ctrl`, `shift`, `alt` and `super`. `cmd`, `meta` and `win` alias `super`.
|
|
101
|
+
- A long `type` is sent in batches of at most 256 events. On failure, `data.applied` is the number of events the engine confirmed.
|
|
102
|
+
- If the engine answered (`busy`, `invalid_input`, `unsupported_input`), resend only the rest of the text.
|
|
103
|
+
- If the reply was lost (`timeout`, `unreachable`, `disconnected`), the last batch may already be on screen. Take a screenshot before you resend anything.
|
|
104
|
+
|
|
105
|
+
## JSON
|
|
106
|
+
|
|
107
|
+
Add `--json` to any command. Success writes one document to stdout and leaves stderr empty. Output shapes: [CLI output](references/cli.md#output).
|
|
108
|
+
|
|
109
|
+
On failure, stdout is empty and stderr has one compact document:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{"status":"error","reason":"busy","message":"Another controller holds control of the desktop.","data":{"httpStatus":409}}
|
|
113
|
+
{"status":"action_required","reason":"invalid_input","message":"Invalid x: '2'.","next":[{"command":"screen-relay help click","argv":["screen-relay","help","click"]}]}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- `status` is `action_required` when the command stopped before any effect and input would let it run. Otherwise it is `error`.
|
|
117
|
+
- Match `reason`, not `message`. `reason` is a stable snake_case code.
|
|
118
|
+
- When `next` is present, run `next[0].command`.
|
|
119
|
+
- `data` holds context: `component` and `logs` after a component failure, `applied` after a partial input batch, `httpStatus` from the engine.
|
|
120
|
+
|
|
121
|
+
Exit codes: [CLI exit codes](references/cli.md#exit-codes).
|
|
122
|
+
|
|
123
|
+
## Reasons and recovery
|
|
124
|
+
|
|
125
|
+
| Reason | Meaning | Recovery |
|
|
126
|
+
| --- | --- | --- |
|
|
127
|
+
| `busy` | Another controller holds input, or a screenshot is already running. | See [One controller](#one-controller). Screenshots still work. |
|
|
128
|
+
| `unauthorized` | Missing or wrong token. | Pass `--token-file FILE` or set `SCREEN_RELAY_TOKEN_FILE`. Or open the `#token=` viewer link. |
|
|
129
|
+
| `forbidden` | The engine rejected `Host` or `Origin`. | Use the `--public` URL or loopback. |
|
|
130
|
+
| `unreachable` | Cannot connect: `Connection refused.`, `The host name did not resolve.` or `The TLS certificate was rejected.` | Check the address, then `screen-relay status --url <URL>`. |
|
|
131
|
+
| `timeout` | No reply within `--timeout`, or `up` was not ready in time. | Raise `--timeout`. For `up`, read the component log. |
|
|
132
|
+
| `not_running` | No session or logs with that name. | `screen-relay up -d`. |
|
|
133
|
+
| `not_found` | No running session for `run` or a skill, or an unknown engine endpoint. | Start the session, or run `screen-relay skills list`. |
|
|
134
|
+
| `already_running` | A session with that name is running. | `screen-relay down --name N`, or pick another name and port. |
|
|
135
|
+
| `component_failed` | The display, desktop, engine, supervisor or an app exited. `data.component` and `data.logs` are set. | `screen-relay logs <component>`. |
|
|
136
|
+
| `missing_dependency` | A host program or the engine binary is missing. | `screen-relay install --yes`, with `--backend wayland` for Wayland. Or `screen-relay doctor`. |
|
|
137
|
+
| `missing_input` | `up` needs setup and has no terminal to ask (exit 2). | `screen-relay install --yes`, then `screen-relay up -d`. Or `screen-relay up -d --yes`. |
|
|
138
|
+
| `missing_command` | `run` was given no app (exit 2). | `screen-relay run -- APP`. |
|
|
139
|
+
| `spawn_failed` | `run` could not start the app. | Check the app name and `screen-relay logs apps`. |
|
|
140
|
+
| `unsupported_input` | The backend cannot produce a character or apply the input. | Use `screen-relay type` for layout-neutral text. |
|
|
141
|
+
| `unsupported_platform` | `up`, `down` or `run` ran off Linux and macOS. | Run host commands on the Linux or macOS machine. |
|
|
142
|
+
| `invalid_config` | A config key or value is invalid. The message names the file and key. | Fix the file and start again. |
|
|
143
|
+
| `invalid_input`, `invalid_option`, `unknown_command` | Usage error (exit 2). | Read the `next` command, usually `screen-relay help <command>`. |
|
|
144
|
+
| `internal` | A bug in screen-relay. | Report it with the command you ran. |
|
|
145
|
+
|
|
146
|
+
## One controller
|
|
147
|
+
|
|
148
|
+
Only one controller sends input at a time: a browser viewer, an SDK control session, or your CLI. A second controller gets `busy` with the message `Another controller holds control of the desktop.`, and nothing is applied. Screenshots, `status` and `capabilities` keep working. Do not retry in a loop. Wait for the other controller to close, then retry once.
|
|
149
|
+
|
|
150
|
+
## Config
|
|
151
|
+
|
|
152
|
+
Keys, defaults, file location and precedence: [config](references/config.md).
|
|
153
|
+
|
|
154
|
+
## Troubleshooting
|
|
155
|
+
|
|
156
|
+
- Run `screen-relay doctor` first. It prints a fix command for each failing check. For Wayland, run `SCREEN_RELAY_BACKEND=wayland screen-relay doctor`.
|
|
157
|
+
- `screen-relay logs` prints the last 200 lines of every component log. `screen-relay logs <component>` selects one: `display`, `dbus`, `desktop`, `engine` or `apps`. Add `-f` to follow.
|
|
158
|
+
- For symptoms and fixes, see [troubleshooting](references/troubleshooting.md).
|
|
159
|
+
|
|
160
|
+
## References
|
|
161
|
+
|
|
162
|
+
- `references/cli.md`: commands, options, output and exit codes.
|
|
163
|
+
- `references/config.md`: config keys, defaults and precedence.
|
|
164
|
+
- `references/sdk.md`: the Node SDK for scripts.
|
|
165
|
+
- `references/wayland.md`: Wayland compositors, attach mode and limits.
|
|
166
|
+
- `references/macos.md`: macOS install, permissions, display choice and limits.
|
|
167
|
+
- `references/troubleshooting.md`: symptoms and fixes.
|
|
168
|
+
- `screen-relay skills get vercel-sandbox`: run screen-relay in a Vercel Sandbox.
|
|
169
|
+
- https://relay.labs.vercel.dev/docs: the published documentation.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# CLI reference
|
|
2
|
+
|
|
3
|
+
The published reference is at https://relay.labs.vercel.dev/docs/cli.
|
|
4
|
+
|
|
5
|
+
Run `screen-relay help` for root help, `screen-relay help <command>` for one command, and `screen-relay help --all --json` for every command's metadata. Help works offline.
|
|
6
|
+
|
|
7
|
+
## VM commands
|
|
8
|
+
|
|
9
|
+
Run these on the Linux or macOS machine that shows the desktop. `up`, `down` and `run` fail with `unsupported_platform` elsewhere.
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
screen-relay install [--backend x11|wayland|all|macos] [--desktop xfce|none|COMMAND]
|
|
13
|
+
[--config FILE] [--yes]
|
|
14
|
+
screen-relay up [-d] [--name NAME] [--config FILE] [--port PORT] [--desktop xfce|none|COMMAND]
|
|
15
|
+
[--display DISPLAY] [--backend x11|wayland|macos] [--output NAME|DISPLAY_ID]
|
|
16
|
+
[--public HTTPS_URL] [--tls-cert FILE --tls-key FILE]
|
|
17
|
+
[--bind ADDRESS] [--timeout SECONDS] [--yes]
|
|
18
|
+
screen-relay down [--name NAME]
|
|
19
|
+
screen-relay logs [component] [--name NAME] [-f|--follow]
|
|
20
|
+
screen-relay run -- <app> [args]... [--name NAME] [--restart]
|
|
21
|
+
screen-relay doctor [--config FILE]
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- `install` sets up the machine without starting a session. It installs the system packages for the backend and builds the engine. It is safe to repeat. When nothing is missing, it reports `unchanged`.
|
|
25
|
+
- `--backend`: `x11`, `wayland` or `all` on Linux, `macos` on macOS. The default is `x11` on Linux and `macos` on macOS. The value also comes from `SCREEN_RELAY_BACKEND` and the config `backend` key. Adding a backend keeps the ones already set up.
|
|
26
|
+
- `--desktop`: the same values as `up --desktop`. With `xfce` on x11, the XFCE packages are installed. With `none` or a command, they are skipped.
|
|
27
|
+
- `--config FILE`: read `backend` and `desktop` from this file.
|
|
28
|
+
- `--yes`, `-y`: install packages without asking. Required when there is no terminal.
|
|
29
|
+
- JSON outcome: `installed` or `unchanged`, with the backends and the engine path under `install`.
|
|
30
|
+
- `up` starts a display (Xvfb on X11, or sway with XWayland on Wayland) or attaches to an existing one. On macOS it attaches to the logged-in user's display and starts no desktop. It then starts the desktop when enabled and the engine, waits until both are ready, and supervises the session. `--timeout` defaults to 30 seconds.
|
|
31
|
+
- Without `-d`, it runs in the foreground. The first Ctrl+C stops the session (exit 130). Piped, it prints only the viewer URL.
|
|
32
|
+
- `--display DISPLAY`: attach to an X display (`:0`) or a Wayland socket (`wayland-1`). It keeps the caller's environment. A Wayland socket needs `XDG_RUNTIME_DIR`. macOS rejects it with `invalid_input`.
|
|
33
|
+
- `--backend x11|wayland|macos`: on Linux, defaults to `x11` when the engine has it, else `wayland`. A `--display` without a colon, such as `wayland-1`, selects `wayland` on its own. On macOS the only backend is `macos`. `x11` and `wayland` fail there with `invalid_input`, and `macos` fails on Linux the same way.
|
|
34
|
+
- `--output NAME|DISPLAY_ID`: capture this Wayland output by name, or a macOS display by its CGDirectDisplayID. `up` fails on x11.
|
|
35
|
+
- `--yes`: when setup is needed, set it up without asking. Without a terminal, `up` never prompts and fails with `missing_input` unless `--yes` is given.
|
|
36
|
+
- `--public HTTPS_URL`: advertises an HTTPS origin. Expects a TLS proxy unless `--tls-cert` is set.
|
|
37
|
+
- Backend setup: [Wayland](wayland.md) and [macOS](macos.md).
|
|
38
|
+
- `down` stops the session and everything it started. It is safe to repeat. JSON outcome: `stopped` or `unchanged`.
|
|
39
|
+
- `logs` prints the last 200 lines of one component (`display`, `dbus`, `desktop`, `engine`, `apps`), or of every component log. `-f` follows; it cannot be combined with `--json`.
|
|
40
|
+
- `run` starts an app on the session desktop and returns its pid. The app shares the desktop's display, the available D-Bus session bus, runtime, config, cache and X authority settings, and it clears ambient capabilities. On Wayland it also sets `WAYLAND_DISPLAY`. On macOS it clears `DISPLAY`, `WAYLAND_DISPLAY` and `XAUTHORITY`. `--restart` restarts the app until the session stops. App output goes to `screen-relay logs apps`.
|
|
41
|
+
- `doctor` checks the machine it runs on and prints a fix command for each problem. On macOS it checks `platform` (macOS 12.3 or later), `engine` and `permissions`. Off Linux and macOS, the platform check fails. The backend comes from `SCREEN_RELAY_BACKEND`, then the config file's `backend` key (from `--config FILE` or the default config), then the engine's default. Use `SCREEN_RELAY_BACKEND=wayland screen-relay doctor` for a Wayland setup.
|
|
42
|
+
|
|
43
|
+
## Client commands
|
|
44
|
+
|
|
45
|
+
Run these on the VM, or on another machine with `--url` and a token file. Each one reaches the engine over HTTP.
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
screen-relay status [--name NAME] [--url URL] [--token-file FILE] [--timeout SECONDS] [--show-token]
|
|
49
|
+
screen-relay screenshot [file] [--url URL] [--token-file FILE] [--timeout SECONDS]
|
|
50
|
+
screen-relay click <x> <y> [--button left|middle|right]
|
|
51
|
+
screen-relay move <x> <y>
|
|
52
|
+
screen-relay scroll <x> <y> [--dx NUMBER] [--dy NUMBER]
|
|
53
|
+
screen-relay key <combo>...
|
|
54
|
+
screen-relay type <text>
|
|
55
|
+
screen-relay type --stdin
|
|
56
|
+
screen-relay input <json>
|
|
57
|
+
screen-relay input --stdin
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- `status` with no URL reads the local session and exits 0 for any existing session. With `--url` (or `SCREEN_RELAY_URL`), it queries a remote engine. A missing session is `not_running`, exit 1.
|
|
61
|
+
- `status --json` puts the session under `session`. These fields name the display server:
|
|
62
|
+
- `backend`: `x11`, `wayland` or `macos`.
|
|
63
|
+
- `waylandDisplay`: the Wayland socket, such as `wayland-1`. Wayland only.
|
|
64
|
+
- `runtimeDir`: the runtime directory of the sway session. Wayland only, when screen-relay starts sway. `down` deletes it.
|
|
65
|
+
- `screenshot` writes `screen.png` by default. `-` writes PNG bytes to stdout (not with `--json`).
|
|
66
|
+
- `click` defaults to the left button. `move` only moves the pointer.
|
|
67
|
+
- `scroll` needs a nonzero `--dx` or `--dy`. `--dy` is vertical wheel notches, positive down. `--dx` is horizontal, positive right. Scrolling moves the pointer to the given point first.
|
|
68
|
+
- `key` presses each physical combo in order, for example `ctrl+l`, `Enter`, `alt+Tab` and `cmd+shift+t`.
|
|
69
|
+
- `type` sends text events. `--stdin` reads the text from standard input.
|
|
70
|
+
- `input` sends a JSON array of 1 to 256 SDK input events, for example `screen-relay input '[{"type":"keyDown","key":4},{"type":"keyUp","key":4}]'`.
|
|
71
|
+
|
|
72
|
+
## Skills
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
screen-relay skills list
|
|
76
|
+
screen-relay skills get <name> [--full] [--json]
|
|
77
|
+
screen-relay skills path [name]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`list` is the default and leaves out hidden skills. `get` prints a skill workflow, including a hidden one asked for by name. `--full` appends its `references/` and `templates/`. `path` prints the skills directory or one skill's directory. An unknown skill is `not_found` (exit 1).
|
|
81
|
+
|
|
82
|
+
## Global options
|
|
83
|
+
|
|
84
|
+
At any position: `-h`/`--help`, `-v`/`--version` (prints only the version), `--json`, `--no-color`, `--name NAME`. `--` ends option parsing. Booleans accept `--no-<name>`. Short options are only `-h`, `-v`, `-f`, `-d` (`up -d`) and `-y` (`install -y`).
|
|
85
|
+
|
|
86
|
+
## Output
|
|
87
|
+
|
|
88
|
+
Queries print data on stdout. Mutations write receipts and next steps on stderr. Piped, `up` prints the viewer URL, `screenshot` prints the saved path, and input commands print nothing. Receipts use `✓`, `!` and `✗` on a TTY, and plain words otherwise.
|
|
89
|
+
|
|
90
|
+
With `--json`, success is one document on stdout, with a trailing newline, and stderr stays empty. It is pretty-printed with two spaces on a TTY and compact otherwise. Failure is one compact document on stderr, and stdout stays empty. A failure document's `next` is optional. `next[].command` is the full command line, and `next[].argv` is the same command split, starting with `screen-relay`. Success may also carry `warnings: [{reason, message}]` and `next`.
|
|
91
|
+
|
|
92
|
+
| Command | Shape |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| `screen-relay up -d --json` | `{"session":{...},"outcome":"started"}` |
|
|
95
|
+
| `screen-relay down --json` | `{"session":{...},"outcome":"stopped"}` or `"unchanged"` |
|
|
96
|
+
| `screen-relay install --json` | `{"install":{"backends":["x11"],"engine":"..."},"outcome":"installed"}` or `"unchanged"` |
|
|
97
|
+
| `screen-relay status --json` | `{"session":{...}}` |
|
|
98
|
+
| `screen-relay screenshot file.png --json` | `{"screenshot":{"path","width","height","bytes"},"outcome":"saved"}` |
|
|
99
|
+
| `screen-relay click`, `move`, `scroll`, `key`, `type`, `input` | `{"input":{"events":N},"outcome":"sent"}` |
|
|
100
|
+
| `screen-relay run -- APP --json` | `{"app":{"pid":N,"command":["APP"]},"outcome":"started"}` |
|
|
101
|
+
| `screen-relay logs engine --json` | `{"logs":{"engine":"..."}}` |
|
|
102
|
+
| `screen-relay doctor --json` | `{"checks":[...],"summary":{"ok","passed","warnings","failed"}}` |
|
|
103
|
+
| `screen-relay skills list --json` | `{"skills":[{"name","description"}]}` |
|
|
104
|
+
|
|
105
|
+
## Exit codes
|
|
106
|
+
|
|
107
|
+
| Code | Meaning |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| 0 | Success, including `status` of any existing session. |
|
|
110
|
+
| 1 | Runtime, network, permission, config or missing-session failure. |
|
|
111
|
+
| 2 | Usage error, invalid value or missing input. |
|
|
112
|
+
| 130 | Interrupted with Ctrl+C. |
|
|
113
|
+
| 128+n | Terminated by signal n. |
|
|
114
|
+
|
|
115
|
+
## Client target
|
|
116
|
+
|
|
117
|
+
Client commands take `--url`, `--token-file` and `--timeout` (seconds, default 10). The target is `--url`, else `SCREEN_RELAY_URL`, else the ready local session named by `--name`, else `http://127.0.0.1:8080` when no session was explicitly selected. A URL is an origin only. Plain HTTP is allowed only for `localhost` and `127.0.0.1`. Remote hosts need HTTPS and a 64-character lowercase hex token. Redirects are refused.
|
|
118
|
+
|
|
119
|
+
Connection failures name the cause in the message: `Connection refused.`, `The host name did not resolve.`, `The request timed out.` or `The TLS certificate was rejected.`
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
The published reference is at https://relay.labs.vercel.dev/docs/configuration.
|
|
4
|
+
|
|
5
|
+
Precedence, highest first:
|
|
6
|
+
|
|
7
|
+
1. Flag.
|
|
8
|
+
2. `SCREEN_RELAY_*` environment variable.
|
|
9
|
+
3. Config file.
|
|
10
|
+
4. Default.
|
|
11
|
+
|
|
12
|
+
`screen-relay up` reads `--config FILE`, then `SCREEN_RELAY_CONFIG`, then `${XDG_CONFIG_HOME:-~/.config}/screen-relay/config.yaml` when it exists. `screen-relay install --config FILE` reads `backend` and `desktop` from that file. A missing explicitly selected file, an unknown key, an invalid type or an out-of-range value stops startup before any process starts. Every problem is reported at once.
|
|
13
|
+
|
|
14
|
+
| Key | Default | Range or meaning | Environment |
|
|
15
|
+
| --- | --- | --- | --- |
|
|
16
|
+
| `display.resolution` | `1280x720` | `WIDTHxHEIGHT`; even width `320..16384`, even height `240..16384` | `SCREEN_RELAY_RESOLUTION` |
|
|
17
|
+
| `display.compositor` | `auto` | `auto`, `on` or `off`, for the XFCE desktop screen-relay starts; `auto` turns the compositor off when `stream.fps` is above 60 | `SCREEN_RELAY_COMPOSITOR` |
|
|
18
|
+
| `stream.fps` | `60` | `10..120` | `SCREEN_RELAY_FPS` |
|
|
19
|
+
| `stream.bitrate.min` | `1M` | Bits per second, `250000..100000000`; a `k` or `M` suffix is 1000-based | `SCREEN_RELAY_BITRATE_MIN` |
|
|
20
|
+
| `stream.bitrate.start` | `8M` | As above | `SCREEN_RELAY_BITRATE_START` |
|
|
21
|
+
| `stream.bitrate.max` | `40M` | As above; require min <= start <= max | `SCREEN_RELAY_BITRATE_MAX` |
|
|
22
|
+
| `server.port` | `8080` | `1..65535` | `SCREEN_RELAY_PORT` |
|
|
23
|
+
| `server.bind` | `127.0.0.1` | Listen address | `SCREEN_RELAY_BIND` |
|
|
24
|
+
| `server.public` | none | HTTPS origin without a path, query or credentials | `SCREEN_RELAY_PUBLIC` |
|
|
25
|
+
| `server.tls_cert` | none | Certificate file; `server.tls_key` must be set too | `SCREEN_RELAY_TLS_CERT` |
|
|
26
|
+
| `server.tls_key` | none | Private key file | `SCREEN_RELAY_TLS_KEY` |
|
|
27
|
+
| `keyboard.layout` | `us` | Comma-separated XKB layout such as `fr,us` | `SCREEN_RELAY_KEYBOARD_LAYOUT` |
|
|
28
|
+
| `backend` | Linux: `x11` when the engine has it, else `wayland`. macOS: `macos` | `x11`, `wayland` or `macos`; `--backend` overrides it | `SCREEN_RELAY_BACKEND` |
|
|
29
|
+
| `desktop` | `xfce` (x11) or `foot` (wayland) | `xfce`, `none`, or a desktop command; defaults to `none` with `--display`; always `none` on macOS | `SCREEN_RELAY_DESKTOP` |
|
|
30
|
+
|
|
31
|
+
Example:
|
|
32
|
+
|
|
33
|
+
```yaml
|
|
34
|
+
display:
|
|
35
|
+
resolution: 1600x900
|
|
36
|
+
stream:
|
|
37
|
+
fps: 30
|
|
38
|
+
bitrate:
|
|
39
|
+
min: 1M
|
|
40
|
+
start: 8M
|
|
41
|
+
max: 40M
|
|
42
|
+
server:
|
|
43
|
+
port: 8080
|
|
44
|
+
keyboard:
|
|
45
|
+
layout: us
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
There is no live reload or resize. Run `screen-relay down`, edit the file, then run `screen-relay up -d`. With `--display`, `display.resolution` is ignored and `up` uses the existing display's size, with a warning. macOS ignores `display.resolution` the same way. Client commands use `SCREEN_RELAY_URL` and `SCREEN_RELAY_TOKEN_FILE` instead of the config file.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# macOS
|
|
2
|
+
|
|
3
|
+
On macOS, `screen-relay up -d` streams the logged-in user's display. It starts no virtual display and no desktop.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install -g screen-relay
|
|
9
|
+
screen-relay install --yes
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- Requires macOS 12.3 or later and Node 22 or newer. Node 24 and newer need macOS 13.5, so use Node 22 on macOS 12.3 through 13.4. Install Node first; the install does not install it.
|
|
13
|
+
- Requires Homebrew and the Xcode Command Line Tools. Without Homebrew, `install` stops and says so.
|
|
14
|
+
- `install` uses Homebrew to install `pkgconf`, `x264` and `libwebsockets`, then builds the `macos` backend. `--backend` accepts only `macos`.
|
|
15
|
+
- `up -d --yes` runs the same setup when it is needed.
|
|
16
|
+
|
|
17
|
+
## Permissions
|
|
18
|
+
|
|
19
|
+
Grant both to the app that starts screen-relay, such as your terminal, then restart that app:
|
|
20
|
+
|
|
21
|
+
- Screen Recording: System Settings > Privacy & Security > Screen & System Audio Recording.
|
|
22
|
+
- Accessibility: System Settings > Privacy & Security > Accessibility.
|
|
23
|
+
|
|
24
|
+
`screen-relay doctor` reports them in the `permissions` check.
|
|
25
|
+
|
|
26
|
+
## Start a session
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
screen-relay up -d
|
|
30
|
+
screen-relay run -- open -a Terminal
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `--display` fails with `invalid_input`.
|
|
34
|
+
- `display.resolution` is ignored with a warning.
|
|
35
|
+
- `--desktop` has no effect. The desktop is always `none`.
|
|
36
|
+
- `run` clears `DISPLAY`, `WAYLAND_DISPLAY` and `XAUTHORITY`.
|
|
37
|
+
|
|
38
|
+
## Choose a display
|
|
39
|
+
|
|
40
|
+
Without `--output`, screen-relay streams the main display. `--output` takes a CGDirectDisplayID, a number. If the ID is not an active display, `up` fails, and the engine log lists the active display IDs.
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
screen-relay up -d --output 69733382
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Limits
|
|
47
|
+
|
|
48
|
+
- The stream uses the display's native pixel size, halved until it fits the engine's maximum frame size.
|
|
49
|
+
- The pointer is not drawn into the video. The viewer shows its own arrow.
|
|
50
|
+
- If the display's size, position or ID changes, the engine stops the stream. Run `screen-relay down`, then `screen-relay up -d`.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Node SDK
|
|
2
|
+
|
|
3
|
+
A script needs the package as a local dependency in its project. The global install (`npm install -g screen-relay`) provides only the CLI.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install screen-relay
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
import { createClient, connect, RelayError } from 'screen-relay';
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Options
|
|
14
|
+
|
|
15
|
+
`createClient(options)` and `connect(options)` take the same options.
|
|
16
|
+
|
|
17
|
+
| Option | Default | Meaning |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| `url` | `http://127.0.0.1:8080` | Engine origin. |
|
|
20
|
+
| `token` | none | The 64-character session token. Required for a remote host. Read it with `screen-relay status --show-token --json`. |
|
|
21
|
+
| `timeout` | `10000` | Milliseconds. The CLI's `--timeout` is in seconds (default 10), so `--timeout 10` is `timeout: 10000`. |
|
|
22
|
+
|
|
23
|
+
## createClient
|
|
24
|
+
|
|
25
|
+
`createClient(options)` returns a client. Each call sends its own request. Coordinates are fractions of the screen from 0 to 1, the same as the CLI.
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
status(): Promise<Status> // engine metrics, not the CLI's session record
|
|
29
|
+
capabilities(): Promise<Capabilities>
|
|
30
|
+
screenshot(): Promise<Uint8Array> // PNG bytes
|
|
31
|
+
click(x, y, { button?: 'left' | 'middle' | 'right' })
|
|
32
|
+
move(x, y)
|
|
33
|
+
scroll(x, y, { dx?, dy? })
|
|
34
|
+
key(...combos)
|
|
35
|
+
type(text)
|
|
36
|
+
input(events) // raw SDK input events
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## connect
|
|
40
|
+
|
|
41
|
+
`connect(options)` opens a control session that owns input until `close()`.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
surface: { width, height }
|
|
45
|
+
capabilities(): Promise<Capabilities>
|
|
46
|
+
status(): Promise<Status>
|
|
47
|
+
screenshot(path?): Promise<Uint8Array> // writes a file when path is set
|
|
48
|
+
input(event): Promise<void> // one raw SDK input event
|
|
49
|
+
close(): void
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Only one controller sends input at a time. See [One controller](../SKILL.md#one-controller).
|
|
53
|
+
|
|
54
|
+
## Errors
|
|
55
|
+
|
|
56
|
+
Failures throw `RelayError`. Its `reason` is one of the reasons the CLI reports. See [Reasons and recovery](../SKILL.md#reasons-and-recovery).
|
|
57
|
+
|
|
58
|
+
## Example
|
|
59
|
+
|
|
60
|
+
```js
|
|
61
|
+
import { writeFile } from 'node:fs/promises';
|
|
62
|
+
import { createClient } from 'screen-relay';
|
|
63
|
+
|
|
64
|
+
const client = createClient();
|
|
65
|
+
await writeFile('screen.png', await client.screenshot());
|
|
66
|
+
await client.click(0.5, 0.5);
|
|
67
|
+
await client.type('echo hello');
|
|
68
|
+
await client.key('Enter');
|
|
69
|
+
```
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
The published guide is at https://relay.labs.vercel.dev/docs/troubleshooting.
|
|
4
|
+
|
|
5
|
+
Start with `screen-relay doctor`. For each reason, such as `busy` or `unauthorized`, see [Reasons and recovery](../SKILL.md#reasons-and-recovery). This page covers symptoms that have no reason code.
|
|
6
|
+
|
|
7
|
+
| Symptom | Cause | Fix |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `screen-relay: command not found` | npm's global `bin` directory is not on `PATH`, or the global install did not finish. | Run `npm install -g screen-relay` again. Then check that `$(npm prefix -g)/bin` is on `PATH`. |
|
|
10
|
+
| `component_failed` from `up`, or `status` shows `failed` | A component exited during startup or after ready. The session stops. | Read `data.component`, then `screen-relay logs <component>`. For `-d`, also read `supervisor.log` in the directory named by `session.logs` in `screen-relay status --json`. |
|
|
11
|
+
| `unreachable` with `Connection refused.` | Nothing is listening on the address. | For a local session, run `screen-relay up -d`. Otherwise check the port. |
|
|
12
|
+
| `unreachable` with `The TLS certificate was rejected.` | The certificate is not trusted or names another host. | Use a trusted certificate for the public host, or pass the local session's certificate. |
|
|
13
|
+
| Engine log says `Cannot listen on 127.0.0.1:8080` | Another process owns the port. | `screen-relay up --port 8081`, or stop the old session. |
|
|
14
|
+
| Engine log names a missing Wayland protocol (`zwlr_screencopy_manager_v1`, `zwp_virtual_keyboard_manager_v1` or `zwlr_virtual_pointer_manager_v1`) | The compositor from `--display` lacks it. | Attach to a supported compositor. See [Linux](https://relay.labs.vercel.dev/docs/linux). |
|
|
15
|
+
| Engine log shows `Unsupported root size` | The attached output is outside 320x240 to 16384x16384, or has an odd side. | Create a headless output of a supported size and pass its name with `--output`. |
|
|
16
|
+
| `missing_input` saying `XDG_RUNTIME_DIR is required` | `--display` on wayland without `XDG_RUNTIME_DIR`. | Export the compositor's runtime directory. If it is `/run/user/$(id -u)`, run `export XDG_RUNTIME_DIR=/run/user/$(id -u)`. |
|
|
17
|
+
| `component_failed` or `timeout` for `display` with `--backend wayland` | sway did not start or did not report its displays. | `SCREEN_RELAY_BACKEND=wayland screen-relay doctor`, then `screen-relay logs display`. |
|
|
18
|
+
| `Cannot open display` with `--display` | Missing `XAUTHORITY` for that display. | Export the session's `XAUTHORITY`. Never use `xhost +`. |
|
|
19
|
+
| Engine log says `Screen capture permission is missing`, `Screen Recording permission is missing` or `Accessibility permission is missing`, or `doctor` fails `permissions` | The app that started screen-relay lacks the permission. | Grant both permissions: [macOS permissions](macos.md#permissions). |
|
|
20
|
+
| Engine log says `Display N not found; active displays: ...` | `--output` is not the CGDirectDisplayID of an active display. | Use one of the listed IDs. |
|
|
21
|
+
| Engine log says `The display changed from ... restart screen-relay to stream it` | The display's size, position or ID changed during the session. The stream stops. | `screen-relay down`, then `screen-relay up -d`. |
|
|
22
|
+
| Blank viewer page or WebCodecs error | The browser lacks H.264 WebCodecs, or the page is not a secure context. | Use a current Chrome, Edge or Safari over `https://` or `http://127.0.0.1`. |
|
|
23
|
+
| Viewer cannot connect through a proxy | The proxy drops WebSocket upgrades or rewrites headers. | Forward `/stream`, `/control`, `/input` and the rest without a path prefix. Keep `Host`, `Origin` and `Authorization`. |
|
|
24
|
+
|
|
25
|
+
## Doctor checks that need a manual step
|
|
26
|
+
|
|
27
|
+
`screen-relay doctor` prints the fix for each failing check. These checks need more than a package install:
|
|
28
|
+
|
|
29
|
+
| Check | Cause | Fix |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| `libx264` on Ubuntu | The x264 package is in the `universe` component. | Run `screen-relay install --yes`. It adds `universe` to `/etc/apt/sources.list.d/ubuntu.sources` and updates apt. If that file does not exist, enable `universe` in your apt sources, run `sudo apt-get update`, then run `screen-relay install --yes` again. |
|
|
32
|
+
| `libx264` on Fedora | x264 comes from RPM Fusion Free. `screen-relay install` stops and prints the `dnf` command when RPM Fusion Free is not enabled. | Run `sudo dnf -y install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm`, then run `screen-relay install --yes`. |
|
|
33
|
+
| `icon decoding` with `bubblewrap failed` | Image loaders sandbox themselves with `bwrap`, which needs unprivileged user namespaces. | Allow them for `bwrap`, with an AppArmor profile or `kernel.unprivileged_userns_clone=1`, then run `screen-relay doctor` again. screen-relay does not turn the sandbox off. |
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Wayland
|
|
2
|
+
|
|
3
|
+
`screen-relay up -d --backend wayland` runs a headless sway desktop. `--display` attaches to a compositor you already run.
|
|
4
|
+
|
|
5
|
+
## Compositors
|
|
6
|
+
|
|
7
|
+
- Tested: sway and labwc.
|
|
8
|
+
- Untested: Hyprland (including Omarchy), river, wayfire and niri. They offer the same protocols, so they should work.
|
|
9
|
+
- Not supported: GNOME and KDE. They do not offer `wlr-screencopy`.
|
|
10
|
+
|
|
11
|
+
A compositor must provide `wlr-screencopy` version 3 with XRGB8888 or ARGB8888 shared-memory frames, the virtual keyboard protocol, and virtual pointer version 2.
|
|
12
|
+
|
|
13
|
+
## Start a headless desktop
|
|
14
|
+
|
|
15
|
+
Set up the Wayland backend first, then start the session as a normal user:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
screen-relay install --backend wayland --yes
|
|
19
|
+
screen-relay up -d --backend wayland
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The session runs sway with XWayland and foot, without a GPU. Add `--desktop none` to run without foot.
|
|
23
|
+
|
|
24
|
+
## Attach to a compositor
|
|
25
|
+
|
|
26
|
+
Run these steps from a terminal inside the compositor session:
|
|
27
|
+
|
|
28
|
+
1. Find the output to capture:
|
|
29
|
+
- sway: `swaymsg -t get_outputs`
|
|
30
|
+
- Hyprland: `hyprctl monitors`
|
|
31
|
+
2. Start screen-relay with the Wayland socket from your environment:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
screen-relay up -d --backend wayland --display "$WAYLAND_DISPLAY" --output OUTPUT
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Replace `OUTPUT` with the output name from step 1. Omit `--output` to capture the first output. `--output` needs the Wayland backend. On x11, `up` fails.
|
|
38
|
+
|
|
39
|
+
- Attach mode needs `XDG_RUNTIME_DIR`, which a terminal in a Wayland session normally sets. If screen-relay reports that it is missing, export the compositor's runtime directory, usually `/run/user/$(id -u)`.
|
|
40
|
+
- Attach mode does not set `DISPLAY`. X11 apps need it, so export `DISPLAY` in the shell that runs `screen-relay up` when your compositor provides XWayland.
|
|
41
|
+
|
|
42
|
+
## Limits
|
|
43
|
+
|
|
44
|
+
- Output width must be 320 to 16384 pixels, and height 240 to 16384 pixels, both even. For a larger screen, create a headless output of a supported size on your compositor, then attach to it.
|
|
45
|
+
- Selecting an output with `--output` needs `wl_output` version 4.
|
|
46
|
+
- The output size cannot change during a session. Run `screen-relay down` and start again to use another size.
|
|
47
|
+
- The cursor image is not streamed. The viewer shows its own arrow.
|