---
title: Remote access
description: Open the viewer or control a session from another machine with an SSH tunnel, a public HTTPS URL, or native TLS.
url: "https://screen-relay.dev/docs/remote-access"
docs_index: /llms.txt
lastUpdated: 2026-11-17
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Open a session's viewer and run its client commands from another machine. A session listens on `127.0.0.1:8080` with no token, so only the VM can reach it by default. Anyone with a session's token can see and control its desktop. A session has one token and no user identity.

## Choose a path

| Path               | Use it when                                                         | Token    |
| ------------------ | ------------------------------------------------------------------- | -------- |
| SSH tunnel         | You have SSH access to the VM.                                      | None     |
| Behind a TLS proxy | A cloud sandbox port, nginx, Caddy, or a tunnel forwards to the VM. | Required |
| Native TLS         | Clients connect straight to the VM and you have a certificate.      | Required |

## SSH tunnel

1. On your machine, open the tunnel:

   ```sh
   ssh -N -L 8080:127.0.0.1:8080 user@your-vm
   ```

2. Open `http://127.0.0.1:8080` in your browser.

The session stays on loopback, so the tunnel needs no token.

## Behind a TLS proxy

1. On the VM, start the session with the public origin:

   ```sh
   screen-relay up -d --public https://desktop.example.com
   ```

   `--public` takes a bare HTTPS origin. It makes the session listen on `0.0.0.0` unless you pass `--bind`, creates a token, and accepts requests only for that host. Pages and apps on any origin can connect when they send the token.

2. Configure the proxy to:
   - forward every path with no prefix, including `/viewer.js`, `/stream`, and `/control` ([endpoints](/docs/protocol#endpoints))
   - forward WebSocket upgrades over HTTP/1.1
   - pass `Host`, `Origin`, and `Authorization` through unchanged, and keep the WebSocket subprotocol header
   - keep `Authorization` and the subprotocol header out of its logs, because the token travels in both

3. Open the viewer link that `up` printed.

Without `--tls-cert`, the engine serves plain HTTP and the proxy ends TLS. The proxy must be the only thing that can reach the port. The engine ignores `X-Forwarded-*` headers.

`up` prints a `TLS proxy` row that names the forwarding target.

## Native TLS

1. On the VM, start the session with your certificate:

   ```sh
   screen-relay up -d --tls-cert fullchain.pem --tls-key key.pem --public https://desktop.example.com
   ```

2. Open the viewer link that `up` printed.

The engine serves HTTPS itself, prints no `TLS proxy` row, and speaks HTTP/1.1 only. Client commands on the VM accept the session's own certificate even when its host name does not match, so a self-signed certificate works there.

## Tokens

screen-relay creates a 64-character lowercase hex token (256 random bits) whenever the session listens anywhere other than `127.0.0.1`, or uses `--public`.

- The token is stored in a `token` file in the session's state directory, readable only by its owner. `screen-relay status --json` shows the path as `tokenFile`.
- `screen-relay status` hides the token unless you pass `--show-token`.
- The viewer reads `#token=` from the link that `up` prints, removes it from the address bar, and uses it only on `https://` or loopback pages. Browsers never send the fragment to the server.
- Each `screen-relay up` creates a new token and ends open connections. To rotate a token, run `screen-relay down`, then `screen-relay up`.

## Control a session from your laptop

1. On your laptop, install the CLI. It needs Node 22 or newer and runs on any OS:

   ```sh
   npm install -g screen-relay
   ```

2. On the VM, run `screen-relay status --show-token`, and copy the token into a file named `token` on your laptop.

3. Set the target once per shell, then run client commands:

   ```sh
   export SCREEN_RELAY_URL=https://desktop.example.com
   export SCREEN_RELAY_TOKEN_FILE=./token
   screen-relay status
   screen-relay screenshot screen.png
   ```

To pass the URL and token per command, use `--url` and `--token-file` instead. Use HTTPS for any remote host. Plain HTTP works only for `localhost` or `127.0.0.1`, and redirects are not followed. The [CLI reference](/docs/cli#client-target) lists the URL rules. In Node, pass the same URL and token to `createClient` ([SDK options](/docs/sdk#options)).

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)