Remote serial port with Cloud Relay

Remote serial port with Cloud Relay

Cloud Relay makes a physical serial port on one of your machines behave as a real port on another. The site machine shares the port, the operator machine opens a connection whose type is Remote Serial (Cloud Relay), and the cloud in between forwards the bytes without reading them.

Both ends dial out to the cloud, so it works across NAT with no public address and no inbound port — the same network posture as Cloud Console. The difference is what crosses the link. Cloud Console is a live window in a browser: text events, frame-limited, view and send. Cloud Relay is a transparent byte pipe speaking RFC 2217 end to end, so everything a local port can do still works:

• Change baud rate, framing and flow control from the operator side, or keep the remote port's own configuration.
• Drive DTR/RTS and Break; the control-line lamps follow the remote port's modem lines.
• Run protocol streams unmodified — Modbus RTU polling, XMODEM/YMODEM file transfer, firmware updates.

By default both machines are signed in to the same account: you can only relay to your own devices. To let a colleague without an account in, use an invite code. For how this path compares with RFC 2217, transparent TCP forwarding and Cloud Console, see Choosing a remote access path.

Share a port (site side)

1. Sign in inside the application (Cloud menu → Sign In).
2. Check Cloud → Cloud Console. The relay rides on the same cloud presence, so the main switch must be on; the consent switches below it stay greyed out until it is.
3. Check Cloud → Allow Cloud Relay. It is off by default and deliberately not implied by Allow Remote Send or Allow Remote Port Control — a relay is the whole port, handed over.
4. Open the serial connection you intend to share. Only serial connections are offered for relay: RFC 2217 describes a serial port, so a TCP or UDP endpoint has nothing for it to control.

While an operator holds the port, the status bar shows "A remote operator is using this port", and the local window keeps displaying the traffic — data with no local sender is a takeover you should be able to see. Unchecking Allow Cloud Relay ends every active relay from this machine at once.

Use the port from another machine (operator side)

1. Sign in with the same account.
2. In a connection's settings, choose Remote Serial (Cloud Relay) as the port type.
3. Pick the target in the "Select a Remote Serial Port" dialog. It lists your online devices and their serial ports, and marks the ports whose sharing side has not allowed relay. The port list is fetched from the device on demand, so it can take a few seconds to fill — up to about 30 seconds when the device is on its slow polling path.
4. Decide who sets the serial parameters — the same rule as an RFC 2217 client: keep "use remote configuration" checked to leave the port as the site configured it, or clear it to push your own baud rate and framing when the connection opens.
5. Start the connection. The status bar reads "Cloud Relay · port · connecting", then "connected" once both ends are paired.

From then on it is an ordinary connection: Text/HEX send and receive, timestamps, logging, control lines, CRC tools and file transfer all work, and it can be bridged onward like any other port.

Share from a headless machine (the spu command)

A site machine does not need a desktop session. The direct-download build ships a small console program spu beside the GUI (the Mac App Store build does not include it):

spu -l                                   # list local serial ports
spu login --email user@example.com       # sign in; prompts for the password without echo
spu -D /dev/ttyUSB0 -b 115200            # raw local terminal (stdin ↔ serial)
spu -D /dev/ttyUSB0 -b 115200 --share    # share this port through Cloud Relay

spu login stores the account session in the same profile the GUI uses; for provisioning scripts, pipe the password to --password-stdin instead of putting it on the command line. -S / --share opens the port and turns on relay consent only — no Cloud Console traffic stream, no remote send, no generic port-control commands — and it is strictly the sharing side: it never selects or dials another machine's port. An idle sharing agent is a control-plane presence; nothing is captured or uploaded until an operator actually engages the port.

Share with a colleague (Remote Assist)

The two sections above are about two machines of your own. To let a colleague who has no account work on the port with you, use an invite code: the site machine mints a time-limited code for one open serial port, your colleague pastes it into their own copy of the application, and they get exactly the port you would have got. They need no registration, no subscription and no bound device; the traffic and the Pro entitlement stay on your side, because handing over the port and paying for it are both yours.

Minting one (site side)

1. Sign in and check Cloud → Cloud Console — an invite rides the same cloud channel.
2. Open the serial port you want to share and choose Cloud → Share Port with a Guest….
3. Pick how long it stays valid (1 / 4 / 12 / 24 hours, 12 by default), add a passcode if you want one, write a label your colleague will recognise, and press "Create Invite".
4. Send them XXXX-XXXX-XXXX or the link. Send the passcode separately — in the same message it defeats the point.

This is independent of Allow Cloud Relay, in both directions: that switch admits your own other machines, an invite admits the holder of the code, to that one port, for that long. A share ends when the port closes, when Cloud Console is switched off, on sign-out and on exit.

Joining (their side)

1. In a connection's settings, choose Remote Serial (Cloud Relay) as the port type.
2. In the "Select a Remote Serial Port" dialog, paste the code or the whole link under Join with an invite code, type the name the host should see, and add the passcode if one is required.
3. Start the connection. The dialog first shows which machine and port the code names, whether the host is online, and whether someone is already on it.

A headless machine does the same with spu --invite:

spu -D /dev/ttyUSB0 -b 115200 --invite --invite-label "bench 3"
spu: invite code ABCD-EFGH-JKLM   link https://alithon.com/r/ABCD-EFGH-JKLM   expires 2026-08-21 18:00

--invite-ttl takes 30m / 4h / 1d (default 12h), --invite-passcode-stdin reads a passcode from a pipe rather than the command line, and Ctrl-C revokes the invite on the way out. It combines freely with --share; the two are separate consents.

What the host keeps

• The status bar reads "Guest Zhang San is using this port" — a port driven from elsewhere has to be visible, and so does by whom.
• The share dialog offers "Disconnect Guest" and "Stop Sharing" at any moment; stopping ends the live session and invalidates the code together.
• The device page under Cloud Sync → Cloud Console lists this machine's live shares and can revoke one remotely — but never create one: minting a share is granting a takeover, and that consent belongs on the machine that owns the port.
• Five wrong passcodes burn the code. An expired code admits no new guest but does not cut a session already in progress — interrupting a firmware update halfway is the worst outcome available.
• Unknown, expired and revoked codes all get the same answer, so nobody can probe for codes that once existed.

Good to know

• One relay per port. A second operator asking for a port that is already relayed is refused loudly rather than silently sharing a byte stream that would give each side half of every reply.
• A relay that drops — either end going offline, the session closed from the other side — ends; it is not silently redialled. Start the connection again deliberately.
• The relay is rate-limited per session. A stream faster than the allowance is throttled with real back-pressure toward the source, and a brief "rate limited" advisory appears; each session also has a data ceiling, after which it is closed.
• Common open failures: the sharing side's Allow Cloud Relay is off (permission_denied), the port is already relayed (relay_busy), the device is offline, or the account has no active Pro entitlement.
• Timing quirks aside, the traffic itself is exactly what a direct RFC 2217 connection would carry — byte-for-byte, escaping included.

Traffic, quota and subscription

• Cloud Relay requires a Pro entitlement — a paid licence or an active subscription. It bills by usage, not by fleet size, and a forgotten full-speed session would drain a free allowance in minutes.
• Relayed bytes are metered against the same monthly cloud traffic allowance and top-up balance as Cloud Console; there is no separate relay quota.
• Budget with this number: a port running flat out at 115200 8N1 in both directions moves about 22.5 KB/s — roughly 81 MB per hour. Most debugging sessions are far below that, but a busy binary stream is not.

Security and privacy

• Sharing is off by default, and consent lives on the machine that owns the port; nothing on the web or in the cloud can switch it on remotely.
• Both legs are outbound encrypted connections. A relay pairs two machines on the same account, or one machine with the holder of an invite code it minted itself — either way the machine that owns the port is what authorises it.
• Within an accepted relay, changing serial parameters and driving DTR/RTS/Break are intentional parts of handing the port over — grant Allow Cloud Relay only where that is acceptable.
• Switching Allow Cloud Relay off or signing out ends all relays immediately. These data flows are disclosed in the Privacy Policy.