Every day

On your phone

Lampson runs on your PC or your server; the phone is the remote control. It installs as an app (PWA), you sign in with your fingerprint or face, and you see and use your workspaces the same as in the browser on the PC.

1. Let the phone reach Lampson§

The phone needs an https address that reaches the hub (127.0.0.1:8080). Pick one:

Synsema tunnel (recommended)§

Lampson runs on Synsema, and the Synsema platform has tunnels: your PC at a fixed https://<id>-tunnel.synsema.app address, with no ports to open, no DNS and no domain of your own. The PC opens one outbound connection and everything comes through it — pages, live events and the terminal (WebSocket).

1. Install the platform CLI, syn, and sign in (once per computer; the free plan is enough):

curl -fsSL https://synsema.com/cli/install.sh | sh      # macOS, Linux
irm https://synsema.com/cli/install.ps1 | iex           # Windows (PowerShell)
syn login                                               # syn signup if you have no account yet

2. Put the hub at that address and let the PC keep it up:

syn tunnel 8080 --name lampson --service

It prints the address, and it is the same every time for this PC and the name lampson. With --service the tunnel starts with the computer, no terminal open: the Startup folder on Windows (when you sign in), a systemd unit on Linux, a LaunchAgent on macOS. Without --service it lives as long as its terminal.

3. Make the hub start on its own too: lampson --install.

4. Pair the phone from the terminal: lampson --pair https://<id>-tunnel.synsema.app (or from the PC, step 2 below).

• The address does not change, so the passkey keeps working after restarts.
• If the PC is off, the address answers 503 with X-Synsema-Tunnel: offline, and the app shows «Tu PC no responde» instead.
• syn tunnel service list shows the tunnels kept running and their last state; syn tunnel service remove lampson stops it (the address stays yours); syn tunnel release lampson gives the address up. Log: ~/.synsema/tunnels/lampson.log.
• Plans: Free has 3 addresses and 5 GB a month, and a browser sees a notice page the first time it opens the address (accept it once; the app's own requests never see it). Pro has no notice and a name of your own: --subdomain mylampson → https://mylampson.synsema.app — a new name is a new domain for the passkey, so pair again.
• Tunnel the hub (8080), never the port of a single workspace: the hub is what asks for the passkey.

Quick tunnel (to try it)§

Install cloudflared (on Windows: winget install Cloudflare.cloudflared) and run:

cloudflared tunnel --url http://localhost:8080

It prints an https://….trycloudflare.com address. No account or domain needed. The address changes every time you start it again, and the passkey is bound to the address: when it changes, pair again.

Persistent tunnel (your PC, always)§

For a fixed address that survives restarts. You need a free Cloudflare account with your domain added (Cloudflare runs its DNS).

1. In the Cloudflare dashboard: Zero Trust → Networks → Tunnels → Create a tunnel, type Cloudflared, name lampson.

2. Copy the install command it shows and run it on your PC. It installs the tunnel as a system service, so it starts with the PC:

cloudflared service install <TOKEN>          # Windows: in a terminal run as administrator
sudo cloudflared service install <TOKEN>     # Linux

3. Under Public Hostname add: subdomain lampson, your domain, service HTTP → localhost:8080.

4. Make the hub start on its own too: lampson --install (on Windows, at logon).

Your address is https://lampson.yourdomain.com. If the PC is off, the app says so («Tu PC no responde») instead of showing the tunnel's error page.

If you prefer the terminal to the Cloudflare dashboard:

cloudflared tunnel login
cloudflared tunnel create lampson
cloudflared tunnel route dns lampson lampson.yourdomain.com
cloudflared tunnel run --url http://localhost:8080 lampson

Your own domain (VPS)§

If Lampson runs on a server with a public IP, you don't need a tunnel: Synsema serves your domain over HTTPS directly.

lampson --domain lampson.yourdomain.com --email you@yourdomain.com

Details and requirements in Docker and servers.

2. Pair the phone§

1. On the PC, open http://127.0.0.1:8080 → dispositivos → emparejar dispositivo.

2. Paste the https address (the tunnel or your domain; with --domain it is already there) and tap Generar QR.

3. Scan it with the phone's camera and tap Crear passkey: fingerprint, face or the screen lock. The QR is valid for 5 minutes and works once.

The passkey stays on the phone (or in your password manager, such as Google's or iCloud's). Lampson only keeps the public key.

On a VPS: from the terminal§

A server has no browser to open 127.0.0.1:8080 in, and pairing can only be started from the machine itself (on purpose: nobody can pair by visiting your domain). SSH in and run:

lampson --pair

A QR code shows up in the terminal: point the phone's camera at it and tap Crear passkey. It is valid for 5 minutes and works once; the link is printed below it in case you would rather open it by hand. With --domain the address is already set; otherwise pass it: lampson --pair https://your-domain. It works on your PC too, with a tunnel. If the saved address does not answer — say, a cloudflare tunnel you already closed: each one comes with a new address — it tells you so instead of showing a QR that leads nowhere.

Another way, without --pair: an SSH tunnel (ssh -L 8080:127.0.0.1:8080 user@your-vps) and open http://127.0.0.1:8080 on your PC — the server sees it as local and the steps above work as they are.

3. Install it as an app§

• Android (Chrome, Edge, Samsung): menu ⋮ → Install app.
• iPhone / iPad (Safari): Share → Add to Home Screen.

Sessions and access§

• The PC itself gets in with nothing, as always. Everything else — a tunnel, the local network, a domain — needs a paired device.
• Another website can never use your Lampson, not even from a browser on the PC: a request from another origin is refused (that covers a page trying to reach 127.0.0.1:8080, the terminal included).
• Use an HTTP tunnel (Synsema, cloudflared) to the hub. A raw TCP forward (ssh -R, ngrok tcp) leaves no trace of where a visitor comes from, so Lampson could not tell it from the PC.
• The session renews itself while you use it: it expires after 30 days unused, and the passkey is asked for again every 90 days regardless.
• In dispositivos you see the paired devices, rename them, sign out or remove one; removing it locks it out at once.
• If the address changes (another quick tunnel, another domain), pair again: the passkey is bound to the address.