screen-relay 0.1.0 → 0.1.1

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/README.md CHANGED
@@ -3,12 +3,12 @@
3
3
  Desktop streaming and control for people and AI agents: watch a desktop in a browser, and click, type, and take screenshots from the shell.
4
4
 
5
5
  <p>
6
- <a href="https://vercel.com/labs#labs-products"><img alt="Vercel Labs Product" src="https://img.shields.io/badge/LABS-PRODUCT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a>
6
+ <a href="https://vercel.com/labs#active-experiments"><img alt="Vercel Labs Experiment" src="https://img.shields.io/badge/LABS-EXPERIMENT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a>
7
7
  <a href="https://www.npmjs.com/package/screen-relay"><img alt="npm version: screen-relay" src="https://img.shields.io/npm/v/screen-relay.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
8
8
  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/LICENSE-APACHE--2.0-97ca00.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a>
9
9
  </p>
10
10
 
11
- screen-relay starts a desktop on a Linux VM, sandbox, or container, or attaches to the display of a Mac, and streams it to a browser as H.264. An agent controls the same desktop one command at a time: it takes a screenshot, clicks or types, and takes another screenshot to check the result. The `screen-relay` CLI, a Node SDK, and an HTTP and WebSocket API all reach the same session.
11
+ screen-relay starts a desktop on a Linux VM, sandbox, or container, or attaches to the display of a Mac or the signed-in desktop of a Windows PC, and streams it to a browser as H.264. An agent controls the same desktop one command at a time: it takes a screenshot, clicks or types, and takes another screenshot to check the result. The `screen-relay` CLI, a Node SDK, and an HTTP and WebSocket API all reach the same session.
12
12
 
13
13
  ## Install
14
14
 
@@ -17,12 +17,12 @@ npm install -g screen-relay
17
17
  screen-relay install # system packages and the engine build (first time only)
18
18
  ```
19
19
 
20
- - **Requirements:** Node 22 or newer. On Linux: Debian, Ubuntu, Fedora, Arch Linux, or Alpine. On macOS: Homebrew and the Xcode Command Line Tools.
20
+ - **Requirements:** Node 22 or newer. On Linux: Debian, Ubuntu, Fedora, Arch Linux, or Alpine. On macOS: Homebrew and the Xcode Command Line Tools. On Windows: Windows 10 or later on x64, with a user signed in at the PC's screen.
21
21
  - **Scripts and agents:** `screen-relay install --yes` skips the confirmation. At a terminal, `install` asks before it installs packages.
22
22
  - **Wayland:** `screen-relay install --backend wayland`. The default backend on Linux is X11.
23
23
  - **Client only:** the npm install alone is enough to control a session on another machine.
24
24
 
25
- Requirements, backends, and Windows are covered in [Getting started](https://relay.labs.vercel.dev/docs/getting-started).
25
+ Requirements, backends, and Windows are covered in [Getting started](https://screen-relay.dev/docs/getting-started).
26
26
 
27
27
  ## Quick start
28
28
 
@@ -37,17 +37,17 @@ screen-relay down
37
37
  ```
38
38
 
39
39
  - `up` prints a viewer link. Open it in a browser with H.264 WebCodecs: current Chrome, Edge, or Safari.
40
- - The engine listens on `127.0.0.1:8080`. From another machine, forward the port with `ssh -N -L 8080:127.0.0.1:8080 user@your-vm`, or see [Remote access](https://relay.labs.vercel.dev/docs/remote-access).
40
+ - The engine listens on `127.0.0.1:8080`. From another machine, forward the port with `ssh -N -L 8080:127.0.0.1:8080 user@your-vm`, or see [Remote access](https://screen-relay.dev/docs/remote-access).
41
41
  - On a machine that is not set up yet, `up` runs the same setup as `install` first.
42
42
  - A successful input command means the engine applied the input, not that the app reacted. Take a screenshot to check.
43
43
 
44
- The full walkthrough is in [Getting started](https://relay.labs.vercel.dev/docs/getting-started).
44
+ The full walkthrough is in [Getting started](https://screen-relay.dev/docs/getting-started).
45
45
 
46
46
  ## How it works
47
47
 
48
- `screen-relay up` starts a session: a virtual display, a desktop, and the engine. On Linux the display is X11 with XFCE or headless Wayland with sway. On a Mac the engine attaches to the display you are logged in to. The engine captures the screen, encodes it as H.264, and serves the viewer, the stream, and the input API on one port. It lowers the bitrate on a slow link. See [How streaming works](https://relay.labs.vercel.dev/docs/how-streaming-works).
48
+ `screen-relay up` starts a session: a virtual display, a desktop, and the engine. On Linux the display is X11 with XFCE or headless Wayland with sway. On a Mac the engine attaches to the display you are logged in to. On Windows it attaches to the desktop of the signed-in user. The engine captures the screen, encodes it as H.264, and serves the viewer, the stream, and the input API on one port. It lowers the bitrate on a slow link. See [How streaming works](https://screen-relay.dev/docs/how-streaming-works).
49
49
 
50
- A session listens on loopback with no token by default. Starting it with `--public` or on another address creates a token that every remote request must send. Only one controller sends input at a time: a browser viewer, an SDK control session, or the CLI. Screenshots still work while another controller holds input.
50
+ A session listens on loopback with no token by default. Starting it with `--public` or on another address creates a token that every remote request must send. Only one controller sends input at a time: a viewer that took control, an SDK control session, or the CLI. A viewer opens view-only, so it can watch while the CLI or SDK sends input. Screenshots still work while another controller holds input.
51
51
 
52
52
  ## For AI agents
53
53
 
@@ -74,16 +74,16 @@ Run `screen-relay --help` for the full list, or `screen-relay <command> --help`
74
74
 
75
75
  | Group | Commands | Docs |
76
76
  |---|---|---|
77
- | Session | `up`, `down`, `status`, `logs`, `run` | [CLI reference](https://relay.labs.vercel.dev/docs/cli) |
78
- | Control | `screenshot`, `click`, `move`, `scroll`, `key`, `type`, `input` | [Client commands](https://relay.labs.vercel.dev/docs/cli#client-commands) |
79
- | Setup | `install`, `doctor` | [Getting started](https://relay.labs.vercel.dev/docs/getting-started), [Troubleshooting](https://relay.labs.vercel.dev/docs/troubleshooting) |
80
- | Agents | `skills`, `help` | [Agent skills](https://relay.labs.vercel.dev/docs/agent-skills) |
77
+ | Session | `up`, `down`, `status`, `logs`, `run` | [CLI reference](https://screen-relay.dev/docs/cli) |
78
+ | Control | `screenshot`, `click`, `move`, `scroll`, `key`, `type`, `input` | [Client commands](https://screen-relay.dev/docs/cli#client-commands) |
79
+ | Setup | `install`, `doctor` | [Getting started](https://screen-relay.dev/docs/getting-started), [Troubleshooting](https://screen-relay.dev/docs/troubleshooting) |
80
+ | Agents | `skills`, `help` | [Agent skills](https://screen-relay.dev/docs/agent-skills) |
81
81
 
82
- Flags, environment variables, and `config.yaml` are documented in [Configuration](https://relay.labs.vercel.dev/docs/configuration).
82
+ Flags, environment variables, and `config.yaml` are documented in [Configuration](https://screen-relay.dev/docs/configuration).
83
83
 
84
84
  ## Platforms
85
85
 
86
- The engine runs on Linux (x64 and ARM64, X11 and Wayland) and on macOS 12.3 or later (Apple silicon and Intel). `screen-relay install` builds it on your machine. On Windows, the npm package provides the client commands, and the engine is built by hand. See [Linux](https://relay.labs.vercel.dev/docs/linux), [macOS](https://relay.labs.vercel.dev/docs/macos), and [Windows](https://relay.labs.vercel.dev/docs/windows).
86
+ The engine runs on Linux (x64 and ARM64, X11 and Wayland), on macOS 12.3 or later (Apple silicon and Intel), and on Windows 10 or later (x64). `screen-relay install` builds it on your machine. See [Linux](https://screen-relay.dev/docs/linux), [macOS](https://screen-relay.dev/docs/macos), and [Windows](https://screen-relay.dev/docs/windows).
87
87
 
88
88
  ## Development
89
89
 
@@ -102,11 +102,11 @@ Run the engine tests with `make test`, which also needs the FFmpeg development l
102
102
 
103
103
  ## Documentation
104
104
 
105
- - [relay.labs.vercel.dev](https://relay.labs.vercel.dev): introduction, guides, and reference
106
- - [CLI reference](https://relay.labs.vercel.dev/docs/cli) and [Configuration](https://relay.labs.vercel.dev/docs/configuration)
107
- - [Node SDK](https://relay.labs.vercel.dev/docs/sdk) and [HTTP API](https://relay.labs.vercel.dev/docs/protocol)
108
- - [Remote access](https://relay.labs.vercel.dev/docs/remote-access): tokens, TLS, and tunnels
109
- - [Docker](https://relay.labs.vercel.dev/docs/docker) and [Vercel Sandbox](https://relay.labs.vercel.dev/docs/vercel-sandbox)
105
+ - [screen-relay.dev](https://screen-relay.dev): introduction, guides, and reference
106
+ - [CLI reference](https://screen-relay.dev/docs/cli) and [Configuration](https://screen-relay.dev/docs/configuration)
107
+ - [Node SDK](https://screen-relay.dev/docs/sdk) and [HTTP API](https://screen-relay.dev/docs/protocol)
108
+ - [Remote access](https://screen-relay.dev/docs/remote-access): tokens, TLS, and tunnels
109
+ - [Docker](https://screen-relay.dev/docs/docker) and [Vercel Sandbox](https://screen-relay.dev/docs/vercel-sandbox)
110
110
  - [Changelog](CHANGELOG.md)
111
111
 
112
112
  ## License
@@ -7,7 +7,7 @@ type Args = Record<string, any> & {
7
7
  interface Target {
8
8
  url: string;
9
9
  token?: string;
10
- ca?: string;
10
+ certificate?: string;
11
11
  connect?: string;
12
12
  timeout: number;
13
13
  signal?: AbortSignal;
@@ -1,4 +1,4 @@
1
- export declare const BACKENDS: readonly ['x11', 'wayland', 'macos'];
1
+ export declare const BACKENDS: readonly ['x11', 'wayland', 'macos', 'windows'];
2
2
  export declare const COMPOSITORS: readonly ['auto', 'on', 'off'];
3
3
  export type ConfigSettings = {
4
4
  display: {
@@ -17,7 +17,7 @@ export type HostArgs = Record<string, unknown> & {
17
17
  export declare function isLinux(): boolean;
18
18
  export declare function requireHost(): void;
19
19
  export declare function which(program: string): string | undefined;
20
- /** Clears Linux capabilities or leaves the command unchanged on macOS. */
20
+ /** Clears Linux capabilities or leaves the command unchanged on macOS and Windows. */
21
21
  export declare function clearedCommand(command: string[]): [string, ...string[]];
22
22
  export declare function spawnCleared(command: string[], options?: SpawnOptions): ChildProcess;
23
23
  export declare function run(command: string[], options?: SpawnOptions): import("node:child_process").SpawnSyncReturns<string>;
@@ -17,7 +17,7 @@ export declare function lockOwnerAlive(file: string): boolean;
17
17
  /** Signals every Linux process carrying this session's SCREEN_RELAY_SESSION marker; on macOS the app watcher stops each app it holds. */
18
18
  export declare function sweep(directory: string, signal?: AbortSignal): Promise<void>;
19
19
  export declare function reap(directory: string, session: SessionData | null, signal?: AbortSignal): Promise<void>;
20
- /** Holds the kernel session lock until close, with flock on Linux and lockf on macOS. */
20
+ /** Holds the session lock until close: flock on Linux, lockf on macOS, and a lock file on Windows. */
21
21
  export declare function lock(name: string, directory: string): Promise<{
22
22
  close(): Promise<void>;
23
23
  }>;
@@ -7,6 +7,7 @@ export declare const BACKEND_PROGRAMS: {
7
7
  x11: string[];
8
8
  wayland: string[];
9
9
  macos: never[];
10
+ windows: never[];
10
11
  };
11
12
  export declare const HINTS: Record<string, string>;
12
13
  export type SessionArgs = HostArgs & {
@@ -30,7 +31,7 @@ export type SessionArgs = HostArgs & {
30
31
  type EngineTarget = {
31
32
  url: string;
32
33
  token?: string | null;
33
- caFile?: string | null;
34
+ certificate?: string | null;
34
35
  connect?: string | null;
35
36
  };
36
37
  export declare function startXvfb(start: (command: string[], options: SpawnOptions) => ChildProcess, auth: string, resolution?: string, signal?: AbortSignal): Promise<string>;
@@ -67,6 +68,8 @@ export declare function compositing(setting: string | undefined, fps: number): b
67
68
  export declare function writeCompositing(configHome: string | undefined, enabled: boolean): void;
68
69
  /** Finds the engine beside the CLI, then the one built for this CLI version, then one on PATH. */
69
70
  export declare function findEngine(): string | null;
71
+ /** Whether a backend attaches to a real desktop instead of starting one. */
72
+ export declare function attaches(backend: string | undefined): boolean;
70
73
  /** Backends the engine reports it was built with; empty when there is no engine. */
71
74
  export declare function compiledBackends(engine?: string | null): string[];
72
75
  /** The command that sets this machine up for a backend. */
@@ -0,0 +1,82 @@
1
+ import { Failure } from '../output.js';
2
+ /** Root of the MSYS2 install that `screen-relay install` sets up on Windows. */
3
+ export declare const MSYS2_ROOT = "C:\\msys64";
4
+ /** The PATH that setup gives the MSYS2 shell, so it searches only the directories setup checks and whatever its login profile adds is not used. */
5
+ export declare const MSYS2_PATH: string;
6
+ /** The MSYS2 paths that setup runs or loads: the shell, the config its login profile reads, and every searched directory with the directories above it that could replace it. */
7
+ export declare const MSYS2_CHECKED: string[];
8
+ /** One access rule as PowerShell reports it: the trustee's security identifier, its account name, and the rights it is granted. */
9
+ export type AclRule = {
10
+ sid: string;
11
+ name: string;
12
+ rights: number;
13
+ };
14
+ /** The owner and allow rules of one path, and whether it is a directory or a file. */
15
+ export type AclObject = {
16
+ path: string;
17
+ kind: 'file' | 'directory';
18
+ owner: string;
19
+ ownerName: string;
20
+ rules: AclRule[];
21
+ };
22
+ /** The allow rules of the MSYS2 paths, and the security identifier of the signed-in account. */
23
+ export type AclProbe = {
24
+ current: string;
25
+ objects: AclObject[];
26
+ };
27
+ /** What setup found at the MSYS2 root: an installation it runs, nothing, or a tree it will not run. */
28
+ export type Msys2Installation = {
29
+ state: 'missing';
30
+ root: string;
31
+ } | {
32
+ state: 'trusted';
33
+ root: string;
34
+ shell: string;
35
+ } | {
36
+ state: 'untrusted';
37
+ root: string;
38
+ reason: string;
39
+ repair?: string[];
40
+ };
41
+ /** The MSYS2 states that stop setup. */
42
+ export type Msys2Problem = Exclude<Msys2Installation, {
43
+ state: 'trusted';
44
+ }>;
45
+ /** The environment that runs relay-engine, with MSYS2's UCRT64 libraries first on PATH on Windows. Other platforms get the environment unchanged. */
46
+ export declare function engineEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
47
+ /** The directory to start the engine in on Windows: its own, so Windows does not search the caller's folder for the engine's DLLs. Undefined elsewhere. */
48
+ export declare function engineWorkingDirectory(engine: string): string | undefined;
49
+ /** The MSYS2 installation on this machine, decided once per process. Call forgetMsys2Installation after setup changes the tree. */
50
+ export declare function msys2Installation(): Msys2Installation;
51
+ /** Drops the remembered decision, so the next check reads the installation again. */
52
+ export declare function forgetMsys2Installation(): void;
53
+ /** MSYS2's bash, after checking that setup trusts the installation it comes from. */
54
+ export declare function msys2Shell(): string;
55
+ /** The failure that says setup will not run the MSYS2 tree it found, and what to do about it. The hint carries no backticks, because the CLI prints a backticked command in place of the hint. */
56
+ export declare function msys2Failure(found: Msys2Problem): Failure;
57
+ /** What to do about an MSYS2 tree that setup does not trust: remove the rights it inherits from C:\ when only those are wrong, else delete it. */
58
+ export declare function msys2Fix(found: Extract<Msys2Installation, {
59
+ state: 'untrusted';
60
+ }>): string;
61
+ /** Removes the rights the MSYS2 tree inherits from C:\, which let every user add files to it, and leaves full control to SYSTEM, Administrators and this account and read access to Users. Returns false when there is nothing to repair or icacls fails. */
62
+ export declare function repairMsys2(): boolean;
63
+ /** Whether the signed-in account, SYSTEM, Administrators, or TrustedInstaller owns every MSYS2 path that setup runs or loads, and no other account can write to it. */
64
+ export declare function trustedAcl(probe: AclProbe): {
65
+ trusted: true;
66
+ } | {
67
+ trusted: false;
68
+ reason: string;
69
+ owned: boolean;
70
+ };
71
+ /** The repair for a tree whose owners setup trusts, or undefined when only deleting it helps; any account's SID works, including one from Entra ID. */
72
+ export declare function msys2Repair(owned: boolean, account: string): string[] | undefined;
73
+ /** The icacls command that replaces the MSYS2 root's inherited rules with full control for SYSTEM, Administrators and this account and read access for Users; Windows passes them on to the tree. */
74
+ export declare function repairCommand(account: string): string[];
75
+ /** Absolute path of winget, or null when LOCALAPPDATA is not set. */
76
+ export declare function wingetPath(): string | null;
77
+ /** The Windows session id of this process, or null when PowerShell cannot report it. */
78
+ export declare function windowsSessionId(): number | null;
79
+ /** The creation time of a Windows process as a FILETIME string, or null when it cannot be read. */
80
+ export declare function windowsStartTime(pid: number): string | null;
81
+ /** Ends a process and every process it started. A failure is ignored because the process may already be gone. */
82
+ export declare function killTree(pid: number): void;