Cursio

Cursio

A LAN-only mesh of trusted personal devices sharing encrypted, resumable sessions.

Input, audio, clipboard, window transfer and file sharing are modules on those sessions — not separate products. Applications never migrate; only pixels, samples, events and file requests cross the link.

The goal is simple: it should not matter which machine an application was launched on.

What it does

• Share one mouse and keyboard across every machine, moving between them by pushing the cursor off a screen edge
• Stream an individual application window to another machine while the app keeps running on its original host
• Carry the clipboard across machines, with formatting and images intact
• Route audio per application, so each remote app appears here as its own named node
• Mount a peer's disks locally, on demand
• Use a peer's USB devices as if they were plugged in here (USB/IP)
• Offer a peer's windows and monitors to Discord, OBS or a browser call here, without drawing them on this desktop
• Receive iPhone/iPad screen mirroring as an AirPlay target for the whole mesh
• Bring an Android phone in as a full peer: its notifications where you are, its SMS, its calls with the voice on the computer (Cursio is the hands-free unit, over Bluetooth), its sound and microphone, its storage and gallery, and its whole screen in a window you drive with the mouse — scrcpy without ADB
• Update itself: a signed build offered by a machine you trust installs side by side and rolls back if it does not come up

What it is not

• Not a remote desktop — you work on a peer by moving the cursor onto its own screen; windows and screens cross the link only as pictures
• Not application or process migration — the app never leaves its host
• Not virtualization
• Not built for the Internet or NAT traversal (LAN only in v0.x)
• Not a replacement for your mixer — Cursio replaces the network hop, not VoiceMeeter or Carla

Supported platforms

• Linux: capture goes through the InputCapture portal + libei on Wayland and evdev on X11. Window capture uses the ScreenCast portal, so what works depends on the compositor; drag-to-transfer on GNOME needs the bundled Shell extension. Audio needs PipeWire, file mounts need FUSE, USB needs usbip-host. Tested on Ubuntu 24.04 and 25.10: a build runs only against the FFmpeg it was linked with, so each is built separately (cargo xtask stage ubuntu24).
• Windows: mounts need WinFsp, USB needs usbipd-win, audio endpoints need the bundled driver (native/cursio-vad). Cursio asks for UAC at start, since Windows silently drops input injected into elevated windows; declining leaves everything else working.
• macOS: a Mac can host a window but cannot yet display a peer's, refuses peers' remote-screen requests, and serves its own volumes but cannot mount a peer's. Input needs the Accessibility permission, window capture the Screen Recording one.
• Android (API 28+): the app in app/ with the node linked in, kept alive as a connectedDevice foreground service. It plays peers' sound and offers its own and its microphone (AAudio), serves its shared storage and gallery, shows its screen on the computers you pick — the one you were at last first — and is driven from there through an accessibility service you turn on once. Notifications reach only the computer you are at; SMS are read and sent from a computer; calls ring there, and on Linux their voice too, with Cursio as the phone's Bluetooth hands-free unit and speaker (cursio bluetooth install). With the network gone it keeps the link over Bluetooth. It reports battery and network; it does not view windows, mount disks or share USB.

Core concepts

No server, no hub. Every node listens for peers dialling in *and* dials the known peers that are down. A node dying doesn't make the others forget it — they mark it offline, carry on with each other, and reconnect when it returns.

Machines are placed on a grid, not by naming a side. --at 1,0 is one machine to the right of 0,0; four in a row are 0,0 1,0 2,0 3,0. Cells, not pixels — nothing needs to know how wide anybody's screen is. A side cannot express order, and a designated centre would make every machine depend on one being up, which is what the mesh exists to avoid.

One session, four independent delivery lanes. Each pair of peers uses separate encrypted TCP connections for interactive traffic, audio, video and bulk data. The six priority classes remain Control > Input > Audio > Video > Metadata > Bulk; a blocked file connection cannot block input. Queues have byte budgets and backpressure, bulk traffic is paced against interactive RTT, and video encoders share an adaptive budget. Connections can be replaced without recreating modules. See transport design.

Input is relative. Mouse motion crosses the wire as dx/dy, never as an absolute position — absolute positioning teleports the cursor and breaks games reading raw input. Keys cross the same way, so while you drive a peer its own shortcuts (Alt+Tab included) act there.

A drag is the only way to start a window transfer. There is no flag for it, so nothing is ever transferred by accident. Receiving stays passive: a peer's window always arrives.

Quick start

Build the CLI:

cargo build -p cursio-core

Pair two machines by running the *same* command on both, with the same password:

cargo run -p cursio-core -- mesh --pair

Then run the mesh with the modules you want:

cursio mesh --at 0,0 --send-input --clipboard

Pairing

Pairing prompts for the password without echoing it. There is no separate "listen" and "join" side: a mesh node already listens and dials at once, and the two ends sort out which one places the call. --pair only opens the ten-minute window in which a machine neither has met is allowed to be called at all.

On first contact the two run SPAKE2 pairing in symmetric mode — the password never crosses the wire — confirm the derived key, remember each other, and hold a session. A wrong password yields two *different* keys rather than an error, so an explicit key-confirmation step follows; only after it is the peer stored. Later runs skip pairing (peer already trusted), so a plain mesh is enough.

With a node already running, cursio pair pairs without a password: it shows a one-time code, and cursio pair (or entering it in the app) on the other machine within five minutes completes it.

Identity and trusted peers are persisted under the platform config directory (~/.config/cursio on Linux, %APPDATA%\cursio\cursio\config on Windows, ~/Library/Application Support/dev.cursio.cursio on macOS).

CLI

cursio mesh            # run as a mesh node — this is how everything runs

cursio status # what the running node is doing: peers, modules, latency, problems cursio pair [CODE] # pair through the running node with a one-time code cursio forget # remove a paired machine and its key cursio wake # wake a paired machine that is asleep (Wake-on-LAN) cursio peers # list peers discovered on the LAN, then exit cursio config # print the config mesh would run with, and where it lives cursio update ... # install, switch and roll back versions cursio portal install # (Linux) make Cursio the ScreenCast portal for --remote-screen

What mesh runs comes from config.toml (cursio config prints its path); every flag overrides the file for that run only, so each module switch comes as a pair (--audio / --no-audio). Settings changed while the node runs are renegotiated on the live links; the few that cannot be are reported as waiting for the next restart.

--files mounts read-write, so anything either machine can reach, the other can change. Linux mounts with FUSE, Windows with WinFsp.

Taking the cursor

Push the cursor off the edge facing a peer to hand it over. To take it back from an idle machine, press Ctrl+Alt+G.

The hotkey is defined in the wire key namespace (Linux evdev), so on a Mac it moves with --mac-modifiers: positional (the default) puts it on Control+ Option+G, swapped on Command+Option+G. Startup logs which physical keys, since a hotkey that quietly relocated is one you cannot find.

--mac-modifiers takes a preset (positional, swapped) or from=to pairs such as rightalt=globe. swapped makes a PC keyboard's Ctrl+C copy on a Mac.

AirPlay

cursio mesh participates in one AirPlay receiver for the whole mesh, named plainly Cursio. Open Control Center → Screen Mirroring and select it. The mesh picks a host that has a free control port and prefers one with a hardware H.264 decoder; if that host goes away, the rest recompute placement and one takes over.

The picture appears wherever you started it: the hosting peer forwards the H.264 untouched through the ordinary window path, so nothing is re-encoded on the way.

Scope today: screen mirroring, transient AirPlay pairing, FairPlay session setup, encrypted H.264 transport and hardware-backed presentation. The audio that accompanies mirroring is not decoded yet. Arbitrary file transfer is not an AirPlay feature — Cursio's own encrypted file channel is the path for that.

Platform video requirements

• macOS — bundles its native AppKit/AVFoundation helper and Apple's hardware decoder; no GStreamer needed
• Linux — GStreamer 1.x with a hardware H.264 decoder (vah264dec, nvh264dec, or vaapih264dec) and a compatible Wayland/GL sink

-