Remote Access

Open app.terminay.com in any browser, on a laptop, tablet, or phone, and work in the same Terminay workspace that is running on your computer. You can also attach it from another Terminay Desktop. Every remote connection uses WebRTC and keeps terminal traffic between that device and your Terminay server.

A Terminay workspace with its projects, terminals, files, and git sidebar open in a browser tab at app.terminay.com

Expose This Server

The desktop app's own server is private until you expose it. Open the connection menu from the server name in the header and choose Expose this server…. The menu then shows Exposed, and Stop exposing this server turns it off again. Stopping exposure prevents new pairing and reconnects; it does not stop your local workspace or its terminals.

To expose the server every time the app starts, enable Automatically expose server on startup under Settings > Remote Access > Remote exposure. It is off by default. You can still stop exposure from the connection menu for the current session without changing the setting.

The right side of the status bar shows the state at a glance: a red dot when this computer's server is not exposed, grey when it is exposed with no devices connected, and blue with a device count when at least one device is connected. Click it to open the connection menu. A standalone server is exposed by its own configuration instead; see Installation.

Pair A Browser

While the server is exposed, choose Create pairing link in the connection menu. The Pair Device dialog shows a QR code and a Copy pairing link button. Open the link in the browser you want to use. A hosted link looks like https://app.terminay.com/?s=your-server#pairing-secret. Pasting it into a browser opens the Terminay app, asks whether to save and connect, and lets you give the connection a name. The secret is short-lived and can be used once.

The new device shows a five-character match code, and the same code appears with the device's name in the Pair Device dialog on the server. Choose Approve only if the two codes match, or Deny to refuse. A request that is not approved within two minutes is discarded.

The session page consumes the secret and removes it from browser history. When you open the link in the app, the browser creates a device key stored by the app for that server. When you open a session-origin pairing URL directly, the key stays on that session origin. Terminay saves the matching public key for that browser.

Save A Connection In The Terminay App

app.terminay.com is an installable connection manager. Open the pairing link in a browser, or choose Add new connection and scan the pairing QR or paste the complete pairing link. The app asks to save and connect, with an optional name (the exposing machine's hostname by default). It then opens the session in a fullscreen iframe so an iPhone Home Screen app can stay full screen.

A direct link such as https://your-server.example/v1/?hostName=…#secret is for Terminay Desktop, not a browser: the direct endpoint is authenticated by Desktop and does not host the web app. Open it from Remote Control → Add connection…. The server's QR command prefers a hosted link when both modes are enabled so a phone camera opens the browser pairing flow.

The manager saves a local bookmark and, for that framed session, the device key used to reconnect. It does not keep the pairing secret, connection ticket, terminal data, or session status. You can rename or forget a saved connection at any time. Forgetting it removes that browser bookmark and its stored device key.

The manager works offline for viewing and organising saved connections. Opening a saved connection loads its stable origin inside the app. Terminay still handles connection and error status on that session page.

Connect Terminay Desktop To Another Server

The desktop app can attach other Terminay servers alongside its own Local server. Open Settings → Remote Access, choose Add server…, paste a hosted or direct pairing link, and choose Continue pairing. Desktop shows the match code while it waits for approval on the server. The server is saved as soon as pairing succeeds, so a failed first connection can be retried from the list without a new link.

One window works with several servers at once. Every attached server's projects appear in the same tab strip, and everything inside a tab, including its terminals, files, settings, macros, recordings, and agents, belongs to that tab's server. The header names the server of the active tab.

  • The connection menu lists each connection with its status. Attach adds a saved server's tabs to the window and Detach removes them. Detaching stops nothing on that server.
  • With more than one server attached, the new project button asks which server the project should be created on.
  • Settings, Macros, and Recordings have a server selector that starts on the active tab's server.
  • A server too old or too new for your app stays listed as incompatible, with its tabs greyed out and a note saying which side to upgrade.

Panels cannot be moved between servers.

Containers And Network Paths

WebRTC media uses UDP separately from HTTPS signaling. Publishing only the server's HTTPS port is not enough: publish the server's UDP media port range and configure --advertise-address with an address the Desktop can route to. Use a hosted pairing link when both exposure modes are enabled.

On macOS and Windows, Docker and Podman run Linux containers inside a virtual machine. Its private container address is not reachable from Desktop, and --network host refers to the VM rather than your computer. Publish the UDP range to the host and advertise the host's routable LAN or VPN address. A direct link such as https://localhost:9443/v1/ reaches a host-published signaling listener only; it does not make the container's UDP media path reachable.

Reconnect Later

Select the saved connection in the Terminay app, or open its stable origin directly, such as https://your-server.terminay.com. The session page asks Terminay for a challenge, signs it with the device key, and receives a short-lived ticket for one new WebRTC connection.

If the browser has not been paired, its device was revoked, or Terminay is unavailable, the session page explains what to do next. Create a new pairing link when pairing is required.

Use The Remote Workspace

Once connected, the browser shows the same workspace as every other client of that server: the same projects, terminals, files, and sidebars. Terminals keep running on the server when you disconnect, and reconnecting picks them up where they were. Each device holds one live connection to a server, so opening the workspace in a second tab takes over from the first.

A Terminay workspace on a phone, with the project tabs across the top and a terminal filling the screen

On a phone, the workspace switches to a compact layout. While the software keyboard is open, a row above it adds Escape, Tab, Control, Shift, Alt, arrow keys, Enter, Paste, and a key to dismiss the keyboard. The modifiers work like Shift on a phone keyboard: tap once to apply one to the next key only, tap again to lock it on, and tap a third time to release it. Dismissing the keyboard releases every modifier.

Pasting in a browser inserts clipboard text. If the clipboard holds only an image, such as a screenshot, Terminay uploads it to a temporary folder on the server and types the file's path into the terminal, which is how you hand an image to a coding agent from a phone. Images can be PNG, JPEG, WebP, or GIF, up to 8 MB. If the browser blocks the clipboard read, Terminay offers a field to paste into instead.

Security And Privacy

The pairing secret stays in the link fragment and is never saved by the connection manager or sent as part of a normal URL request. The private device key is non-extractable. When you open a server inside the installed app, that key is stored by the app for that server only. When you open the session address directly in the browser, the key stays on that session origin.

The signaling relay helps the browser and Terminay establish WebRTC. It does not proxy terminal traffic. Terminay can provide STUN or TURN configuration when a network needs it.

Each session origin is isolated from the others. The installed app stores only that server's reconnect key for framed sessions. The remote workspace bundle is authenticated and integrity-checked before it is cached at the session origin.

Manage Access

Terminay Settings, Remote Access category, showing the current server and connection management

Open Settings → Remote Access, or the manage button beside Connections in the connection menu. Exposure shows the exposure state, devices waiting for approval, Trusted browsers, and Live connections. Choose Revoke on a trusted browser that should no longer have access; a revoked device cannot reconnect until it is paired again.

Reset server identity… revokes every paired device at once and closes their connections. Each device then has to pair again.

Under Servers, select a saved server to rename it, Forget it, or Revoke access. Forgetting only removes the saved profile from this computer. Revoking also invalidates this device on that server.

Troubleshooting

  • Pairing link expired or already used: create a fresh pairing link in Terminay.
  • Direct link opened in a browser: copy the link into Terminay Desktop under Settings → Remote Access → Add server…. Direct links cannot be paired from a browser.
  • Connection needs pairing: open a new pairing link in that browser.
  • Browser was revoked: pair the browser again if you want to restore access.
  • WebRTC stays in checking or disconnects shortly after connecting: signaling may work while UDP media is blocked. Check that the advertised UDP range is published and reachable, then compare the local candidate-pair type, protocol, and state in Desktop and server diagnostics. A loopback direct origin is signaling-only for a container.
  • Desktop says the connection was lost: pairing already succeeded and the server is saved. Retry it from the connections list; you do not need a new link. Desktop gives a connection up once its network path has been down for 15 seconds.
  • Pairing seems stuck on the match code: the request is waiting for approval on the server. Approve it there, or press Cancel in Desktop to withdraw it.
  • WebRTC cannot connect: check the session page message, then retry or check the network's STUN/TURN configuration.
  • Wrong page: open the exact session origin in a saved connection. Use app.terminay.com only to manage bookmarks.