Remote Access

The phone talks to the runtime host, the sidecar that owns your terminals, never to the desktop window. It gets there over a direct WebSocket to the runtime’s mobile gateway, which is what pairing sets up, or through an optional encrypted relay when no direct path exists. Pairing itself is covered in Mobile Companion.

Direct Connections#

The gateway lives under Settings → Mobile Devices → Mobile Gateway. Enable Mobile Access turns it on; it listens on port 6768 by default, bound to whatever the Connection Mode chooses:

• This Device binds to loopback, so only this machine can reach it.
• Tailscale binds to this machine’s Tailnet IPv4 address.
• NetBird binds to this machine’s NetBird address, and NetBird Endpoint picks whether pairing offers carry the IP Address, the DNS Hostname, or the interface address.
• Manual lets you set Bind Host yourself.

A mode takes effect when you pick it, and Apply saves Bind Host and Port. Changing the gateway restarts it, which disconnects connected phones. The address in a pairing QR comes from the mode, so choose it before you pair.

The gateway speaks plain WebSocket, and pairing secrets and device tokens are bearer credentials, so the runtime and the phone accept ws:// only where the network already protects the traffic:

• a loopback address such as localhost or 127.0.0.1
• a private overlay address in 100.64.0.0/10, or Tailscale’s fd7a:115c:a1e0::/48
• a NetBird DNS hostname generated by the NetBird mode

Everything else must be wss://. The gateway does not terminate TLS itself, so put a TLS proxy or tunnel in front of it and enter its address in Endpoint under Link A Device. That public port may differ from the gateway’s port. A wildcard bind such as 0.0.0.0 needs an explicit endpoint. On Windows, if the phone cannot connect, allow Alera through Windows Firewall for incoming connections on the gateway port.

Recommended: Tailscale#

alera mobile --json enable --tailscale does the same from a terminal. Plain ws:// is fine here because Tailnet traffic rides Tailscale’s WireGuard tunnel. If the phone cannot connect, check that its Tailscale app is connected and that your Tailnet’s access rules allow it.

The Encrypted Relay#

When no network path reaches the runtime, the relay carries the same connection over the internet. It needs:

• the desktop runtime signed in to an Alera account under Settings → Account
• Enable Remote Access turned on under Mobile Gateway; it is off by default
• the phone signed in to the same account under Settings → Alera Accounts

The phone tries the direct path first: for a paired host it dials the paired address with a three-second limit, and falls back to the relay only when that attempt fails at the network level, such as unreachable, refused, or timed out. An authentication, TLS, or protocol error is shown instead of being routed around. A runtime your account can see but this phone never paired still appears in the host list, and it always connects through the relay.

The relay is live only. Nothing is queued while either side is offline, a dropped connection loses whatever was in flight, and reconnecting starts a fresh handshake without replaying commands. The runtime must be running and online for the phone to find it.

On the desktop, Relay Status reports the relay connection, and phones using it are listed under Connected Remote Devices as Connected through relay. Their access comes from your account, so there is no rename or revoke there: turn off Enable Remote Access to disconnect them all.

What The Host Cards Say#

Each host card on the phone shows how it is connected:

• Ready via direct or Ready via relay: connected, and over which path.
• Connecting: an attempt is in progress.
• Retrying at a time: a network failure; Retry tries now.
• Unavailable: not connected; Retry tries again.
• Sign-in or connection review required: the failure was not a network problem, so automatic retries stop.
• Discovery unavailable. Showing the last known host.: the account service could not list runtimes, so the card keeps the last one it saw.

What The Relay Can And Cannot See#

The relay runs on Cloudflare at api.alera.build, and Alera treats it as hostile transport. It can observe connection metadata, timing, frame sizes, how many peers are connected, and whether forwarding succeeds. It cannot read commands, terminal output, workspace content, or the protocol messages themselves. The runtime and the phone agree on keys with X25519, derive a separate key for each direction with HKDF-SHA256, and encrypt every frame with ChaCha20-Poly1305, rejecting replayed, reordered, or altered frames. The relay stores no frames.

The account service authorizes each connection with a grant that lasts 120 seconds and is renewed on the open connection, so revoked access, such as a deleted account, stops working no later than when the current grant expires.