Protocol

Message format

Every message is one JSON object. A request names a command in t; include an id when you want a correlated reply (reads), omit it for fire-and-forget (HID writes).

// request  → fire-and-forget (no id)
{ "t": "hid.move", "dx": 30, "dy": -5 }

// request  → with id, expects a reply
{ "t": "screen.pixel", "id": 7, "x": 100, "y": 50 }
// response →
{ "id": 7, "r": 139, "g": 0, "b": 0 }

// subscribe → the server then pushes frames as state changes
{ "t": "subscribe", "events": ["mouse", "input"] }
{ "t": "mouse", "x": 812, "y": 344 }

On connect, the server sends a hello frame with the protocol version, whether auth is required, and (on remote.luau) which danger gates are enabled — so a client can verify compatibility and capability with no round-trip.

Command surface

The full surface below is served by remote.luau (protocol 1.2). The minimal remote_access.lua (protocol 1.1) serves only the HID / Screen / System / Input / Clipboard / Window rows plus hello, ping, auth, lua.exec, subscribe, unsubscribe. Send { "t": "commands", "id": 1 } to introspect exactly what a given server exposes.

Category	Commands
HID writes	`hid.down`, `hid.up`, `hid.press`, `hid.combo`, `hid.type`, `hid.typewriter`, `hid.move`, `hid.move_to`, `hid.move_smooth`, `hid.scroll`, `hid.set_mouse_mode`, `hid.get_mouse_mode`
Screen	`screen.pixel`, `screen.pixel_hex`, `screen.resolution`, `screen.capture`, `screen.capture_window`, `screen.displays`, `screen.search_color`
System	`system.mouse`, `system.window`, `system.time`, `system.screen`, `system.exec`, `system.exec_detached`
Input	`input.keys`, `input.is_down`, `input.duration`, `input.modifiers`, `input.mouse_pos`
Clipboard	`clipboard.get`, `clipboard.set`
Window	`window.list`, `window.find`, `window.get_title`, `window.get_class`, `window.get_pos`, `window.get_pid`, `window.is_visible`, `window.is_active`, `window.activate`, `window.move`, `window.minimize`, `window.maximize`, `window.restore`, `window.hide`, `window.show`, `window.set_title`, `window.set_always_on_top`, `window.set_transparency`, `window.close`, `window.kill`, `window.wait`, `window.wait_active`, `window.wait_close`
App	`app.front`, `app.is_front`, `app.is_running`, `app.is_hidden`, `app.activate`, `app.hide`, `app.quit`
Process	`process.exists`, `process.list`, `process.kill`*
Env	`env.get`, `env.set`, `env.home`, `env.config`, `env.data`, `env.desktop`, `env.documents`, `env.downloads`, `env.appdata`, `env.temp`
Hash / Codec	`hash.md5`, `hash.sha1`, `hash.sha256`, `hash.sha512`, `hash.crc32`, `hash.hmac`, `codec.base64`, `codec.base64_decode`, `codec.hex`, `codec.hex_decode`
Regex	`regex.is_match`, `regex.find`, `regex.find_all`, `regex.replace`, `regex.replace_all`, `regex.split`
Config (TOML)	`config.parse_toml`, `config.to_toml`, `config.read_toml`, `config.write_toml`
File†	`file.read`, `file.read_bytes`, `file.write`, `file.append`, `file.exists`, `file.delete`, `file.list`, `file.mkdir`, `file.rmdir`, `file.is_dir`, `file.is_file`, `file.size`, `file.time`, `file.copy`, `file.move`, `file.read_json`, `file.write_json`, `file.script_dir`
Net (HTTP)	`net.get`, `net.post`, `net.put`, `net.patch`, `net.delete`, `net.head`, `net.request`
Dialog	`dialog.message`, `dialog.confirm`, `dialog.open_file`, `dialog.save_file`, `dialog.open_dir`
Math	`math.random`, `math.gaussian`, `math.scale`, `math.spline`, `math.resample`, `math.interpolate`, `math.time_comp`
Macro	`macro.record`, `macro.finish`, `macro.play`, `macro.stream`, `macro.abort`, `macro.stop_all`
Audio	`audio.beep`, `audio.play`, `audio.stop`, `audio.pause`, `audio.resume`, `audio.is_playing`, `audio.set_volume`, `audio.get_volume`, `audio.stop_all`, `audio.set_master_volume`, `audio.get_master_volume`
Timer	`timer.after`, `timer.every`, `timer.cancel`, `timer.cancel_all` (push stream: `timer`)
Registry (Windows)	`registry.read`, `registry.write`, `registry.delete_value`, `registry.delete_key`, `registry.create_key`
UI	`ui.notify`, `ui.get`, `ui.get_all`, `ui.schema`
Log / Script	`log.info`, `log.warn`, `log.error`, `log.debug`, `script.reload`, `script.exit`
Events	`subscribe`, `unsubscribe` (streams: `mouse`, `window`, `input`, `timer`)
Meta	`hello`, `ping`, `auth`, `commands`, `lua.exec`*

* gated off by default (see Authentication). † sandboxed to the script directory and gated behind ALLOW_FILE. system.window reads the active (foreground) window; the window.* commands list, find, activate, move, and wait on windows. hid.move_smooth glides the cursor to a point over a duration server-side (one call instead of streaming hid.move frames); screen.capture_window captures a single window by handle or title without computing a region. screen.capture (protocol 1.1.0+) returns a display as a base64 PNG at native resolution plus its geometry and the cursor position, and screen.displays enumerates monitors with signed virtual-desktop origins — together the basis for screenshot-driven, computer-use-style automation. Async commands (net.*, dialog.*, window.wait*, hid.press, hid.typewriter, hid.move_smooth) run in a coroutine on the server and reply when the underlying call completes — always include an id for them. Screen, Window, and Registry commands depend on platform support — Screen and Window are limited or absent on Linux, Clipboard is Windows/macOS, and Registry is Windows-only. See Platforms & limits.

Authentication

Auth is off by default (fine on localhost; risky on a LAN, since the server binds 0.0.0.0). To require a token:

remote.luau — set the Auth token field in the script’s settings panel. It is compared over SHA-256 (so timing can’t leak its length or prefix) and is redacted from ui.get/ui.get_all so an authenticated client can’t read it back.
remote_access.lua — set AUTH_TOKEN at the top of the script before installing.

Either way the client then sends { "t": "auth", "token": "..." } first; every non-handshake command is refused with unauthenticated until it does. Dangerous surfaces are gated off by default in remote.luau and must be enabled by editing the file constants (they are deliberately not wire-flippable): ALLOW_EXEC (shell exec, process kill), ALLOW_FILE (filesystem, TOML files), ALLOW_REGISTRY (registry writes), and ALLOW_LUA_EXEC (arbitrary Lua via lua.exec). A gated command returns disabled when its flag is off. Leave these off unless you trust every client that can reach the port.

Performance

Measured on localhost (Windows host, release build):

Metric	Value
RPC round-trip p50	~1 ms
RPC round-trip p99	~2 ms
Sustained RPC throughput (16 in-flight)	~10,000 req/s
Server-side message drain	~12,000 msg/s
Fire-and-forget wire throughput	~100,000 msg/s

Round-trips are sub-millisecond over localhost and a wired LAN — the transport won’t be your bottleneck.

Getting Started

Concepts

Cookbook

Reference

Remote Control

Help

Message format

Command surface

Authentication

Performance

​Message format

​Command surface

​Authentication

​Performance

Message format

Command surface

Authentication

Performance