Remote Access

Remote Access lets you use Terminay terminals from another browser on the same network, or through an origin-isolated WebRTC Relay session when local HTTPS is unreachable.

Terminay Remote menu showing server controls, QR type choices, addresses, and active connections

Start And Stop

Open the Remote menu in the app header. Choose Start Server to turn Remote Access on, or Stop Server to turn it off. You can also open Remote Access Settings and use Pair Device or Stop Remote Access.

Terminay pairing dialog showing Local Network and WebRTC Relay QR choices

Pair A Browser

Choose Start Server & Show QR or Show Pairing QR. Scan the QR code from your phone, or copy the pairing link and open it in another browser. A QR is for adding or re-adding a browser. In WebRTC Relay mode each QR/link creates a one-time pairing room: the first successful pairing consumes it, then Terminay rotates to a fresh room. Show the QR again when you want to add another browser.

In WebRTC Relay mode, Terminay asks you to choose a 6-digit pairing PIN before it generates a production QR code. The phone asks for that PIN after scanning, and the desktop checks it before it creates a paired device. This protects against someone nearby scanning the QR code before you do.

If Terminay shows multiple addresses under Connect To or Available Addresses, choose the one your other device can reach. On many local networks that address begins with 192. or 10..

Terminay Remote Access settings showing a pairing QR code and device management

Manager And Saved Sessions

WebRTC Relay has two public origins with different jobs. app.terminay.com is the manager: it can remember non-secret session origins, labels, timestamps, and local status. It does not store QR secrets, reconnect grants, device keys, PINs, terminal tickets, terminal output, command history, file names, or session-subdomain browser storage.

Each saved WebRTC relationship lives on its own session subdomain, such as https://0123abcd.terminay.com/v1/. That exact origin stores the browser's device key, remote app cache, local preferences, and reconnect grant. The manager opens that origin; it does not embed it or import full QR links with fragments.

After a successful WebRTC pairing, the session page can offer Save to Manager. Saving sends only non-secret metadata to app.terminay.com. Later, opening the saved session tries to reconnect with the desktop-issued grant, so you do not need a fresh QR while that grant is still valid.

Saved Reconnect

The default WebRTC saved-session lifetime is 24 hours. During that window, a paired browser can reopen its saved session link and reconnect without scanning a new QR code. The browser still authenticates every terminal connection: it proves possession of the reconnect grant, signs a device-key challenge, and sends the desktop PIN over the encrypted desktop channel before Terminay issues a new terminal ticket.

For a smoother user experience, the session subdomain can remember the verified PIN in a host-only cookie. That means you normally enter the PIN once for that saved session. Later reconnects use the cached PIN automatically. If Terminay rejects the cached PIN, the session page clears it and asks you to enter the current PIN again.

If the reconnect grant is expired, revoked, missing, or belongs to a different session origin, the session page asks for a fresh QR. Terminay can also offer shorter or longer grant lifetimes in Remote Access settings, including 1 hour, 24 hours, 7 days, or an advanced until-revoked option.

Use The Remote Browser App

In the remote browser app, enter a device name, scan or paste the pairing link, then select Pair Device. After pairing, the browser remembers this host.

The remote app shows your projects and terminal sessions as tabs. Select a session to attach to it, type normally, and use Focus, Clear, Reset, Settings, or Disconnect from the top menu. On touch devices, Terminay adds quick keys for Ctrl, Alt, Escape, Tab, arrows, paging, zoom, and common control shortcuts.

Remote sessions mirror active Terminay terminals. If there are no terminals running, the browser app shows No active sessions. Closed sessions disappear, and exited sessions are marked as exited.

Terminay session subdomain connected to a remote terminal showing file listings and README contents

WebRTC Relay Security

WebRTC Relay mode is designed so the relay can help the phone and desktop find each other without being trusted to read terminal traffic or rewrite the WebRTC handshake. The relay stores short-lived room state and forwards signaling messages, but the browser and desktop authenticate the important signaling payloads with a secret that is only in the QR code.

New WebRTC pairing QRs use a compact versioned link like https://session.terminay.com/v1/#secret. The subdomain is public and identifies the reusable session origin. The fragment secret stays in the browser, is removed from history as soon as the bootstrap reads it, and is expanded locally into the relay join token, pairing token, signaling authentication token, asset install key, and CSRF seed for one pairing room.

app.terminay.com is the manager origin. It stores only non-secret session metadata such as saved session origins and labels. The actual remote app, pairing, PIN entry, service worker, Cache Storage, and any future session cookies live on the unique session subdomain. A custom or forked remote app from one session cannot read another session's storage by sharing the manager origin.

The desktop registers the relay room with roomId, the expiry, and a hash of the relay join token. The phone proves it scanned the QR by sending the relay join token over the signaling WebSocket. The relay compares the token hash before it forwards the phone's join request.

After the phone joins, the desktop creates the WebRTC offer. The offer, answer, and ICE candidates are signed with HMAC-SHA256 using the QR-only signaling authentication token. Both sides verify these signatures before applying the WebRTC messages. If a relay, proxy, or database layer rewrites the SDP fingerprint or ICE candidate, verification fails and the WebRTC connection is not accepted.

Once the signed WebRTC handshake is established, the phone downloads the remote app bundle from the desktop over an encrypted WebRTC data channel. Pairing then happens inside that channel: the phone sends the Terminay pairing token, creates a device key pair, and the desktop stores the public key for future challenge-response authentication.

During first pairing, the browser must also send the PIN inside the encrypted desktop channel before the desktop accepts the pairing token. During saved reconnect, the browser must send the PIN again before the desktop issues a terminal ticket. The PIN hash is stored in Terminay's local settings; the QR code, manager, and relay do not contain the PIN.

The session subdomain may store the verified PIN in a host-only __Host-terminay_pin cookie with Secure, SameSite=Strict, Path=/, and no Domain attribute. It is intentionally readable by the session app so it can submit the PIN to the desktop, but it is scoped to that exact session subdomain. It is not available to app.terminay.com or to other session subdomains, and it is not sufficient by itself without the saved device key and reconnect grant.

This means the signaling relay can see room ids and WebRTC metadata, but it cannot transparently man-in-the-middle the encrypted data channel or authorize a terminal session on its own.

Manage Trust And Activity

Use Remote Access Settings to manage devices and connections.

  • Trusted Browsers shows saved browsers, their session origin, saved reconnect status, when they were added, when they were last seen, and whether any are live now. Use Revoke Browser to remove access and invalidate that browser's saved reconnect grant.
  • Active Connections shows connected browsers and how many sessions each has attached. Use Close to disconnect one.
  • Recent Audit Log shows recent events such as pairing, authentication, connection open/close, device revocation, and connection revocation.

Origin, Binding, And TLS

Remote Access requires HTTPS. By default, Terminay uses https://localhost:9443, binds to 0.0.0.0, and generates a self-signed certificate if TLS paths are blank.

In Settings > Remote Access > Host & Origin, set the exact HTTPS origin browsers should use, such as https://terminay.example.com. The origin must start with https:// and must not include a path, query, or fragment.

Set Bind address to the local interface Terminay should listen on. In TLS, leave the certificate and key paths blank for an auto-generated self-signed certificate, or provide PEM certificate and private key paths.

Production WebRTC Relay uses wildcard DNS and TLS for *.terminay.com. Local development can map representative hosts such as app.terminay.test, session-a.terminay.test, and session-b.terminay.test to 127.0.0.1 so manager and session-origin behavior can be tested separately.

Security And Troubleshooting

Only pair browsers you trust. Anyone with an active paired browser can interact with your terminal sessions. Revoke lost or shared devices, close suspicious active connections, and stop the server when you do not need remote access.

A self-signed certificate may show a browser warning. Use your own trusted certificate for a smoother remote setup. If pairing or authentication fails, check that the browser is opening the same HTTPS origin shown in Terminay, that the QR/link has not expired, that the selected address is reachable, and that your firewall allows the configured port.

  • Expired QR: show the pairing QR again in Terminay and open the new code.
  • Already-used QR: WebRTC QR links are one-time pairing rooms. Use the fresh QR currently shown in Terminay.
  • PIN prompt on saved reconnect: enter the current Terminay PIN. This happens if the session has no cached PIN or Terminay rejected the cached one.
  • Expired or revoked saved session: open Remote Access in Terminay and create a fresh WebRTC QR for that session or pair a new session.
  • Wrong host: WebRTC links must open on the exact session subdomain and version path shown by the QR, not on app.terminay.com.
  • Relay unavailable: check the WebRTC relay status message, then retry from a fresh QR or use Local Network mode.
  • WebRTC failed: some networks block direct peer connections. Configure STUN/TURN in Remote Access settings or switch to Local Network mode when both devices are on the same network.
  • TURN unavailable: Terminay can use configured ICE servers, but production TURN credentials must be short-lived and separate from terminal secrets.
  • Asset verification failed: reload from a fresh QR. The browser rejects remote app files whose hashes do not match the desktop manifest.