Sessions from the terminal: host, sessions, connect, attach

These four subcommands drive Reach Sessions without touching the tray — host a terminal on a server, list what's online, attach from anywhere. All of them need you to have signed in via the tray on that machine once (see the CLI reference).

reach host — host sessions headlessly

reach host [--session NAME] [--shell CMD] [--label LABEL] [--force-native]

Flag	Default	Meaning
--session	main	Name of the first session to open.
--shell	$SHELL, else /bin/sh	Command run for new sessions.
--label	your hostname	Host name shown to viewers (they see it as LABEL (sessions)).
--force-native	off	Use Reach's own PTY broker even if tmux is installed.

It blocks until you press Ctrl-C (or the process gets SIGTERM), which stops hosting. On start it prints what it's doing:

$ reach host --label build-box
hosting sessions as "build-box" via https://sg.reachgateway.net
initial session: main
tmux detected — viewers see your existing tmux sessions (tmux ls). New: tmux new -s <name>
share: add a viewer's TYO ID from the tray ("Add viewer"), or sign in on your own device with the same account
viewers attach with:  reach connect build-box <session>
Ctrl-C to stop hosting.

tmux behaviour: if tmux is on PATH, Reach publishes your existing tmux sessions (tmux ls) and attaching joins them. New sessions are created with tmux new -s name. Without tmux — or with --force-native — Reach serves fresh shells from its own PTY broker, and a session that nobody is attached to still keeps running on the host.

Headless servers: reach host is the intended way to host from a machine with no desktop. Run it under tmux/screen, nohup, or a systemd user service so it survives your SSH session ending. It runs as your user and uses your saved sign-in — there's no service account.

reach sessions — list hosts and sessions

$ reach sessions
build-box (sessions)  (a1b2c3…)
    main
    deploy  [1 attached]
laptop (sessions)  (d4e5f6…)
    main

Attach:  reach connect <session>            (or: reach connect <host> <session>)

Only hosts that are online and have at least one session are listed; your current machine is skipped. [N attached] shows how many viewers are on a session. If nothing is listed you'll see a reminder to enable Host sessions on this PC on the host.

reach connect — dial and attach

reach connect <session>
reach connect <host> <session>

With one argument, Reach first looks for an online session with that name; if exactly one host has it, you're attached. If none does, the argument is treated as a host and you get its main session (or its only session). Ambiguity prints the options:

session "main" is hosted on multiple machines:
  build-box (sessions)  (a1b2c3…)
  laptop (sessions)  (d4e5f6…)
pick one: reach connect <host> main

Host matching is loose and case-insensitive — build matches build-box (sessions) — and prefers the online host that actually has the session you asked for.

The connection goes peer-to-peer when you and the host are on the same network, otherwise through the gateway relay. Either way Reach opens a local port and attaches your terminal to it in raw mode, so keys, colours and window resizes pass straight through.

Detaching: Ctrl-]

Press Ctrl-] to detach. The session keeps running on the host and you can connect again later. This works for every kind of session; on tmux-backed sessions the usual Ctrl-b d also works. Closing the terminal window detaches too.

If you were granted read-only access you'll see attached read-only — your keystrokes are ignored by the host.

reach attach — attach to a port the tray already opened

reach attach --port P --session NAME

This is the low-level half of connect: it assumes something has already dialed the host and is listening on local port P. The tray uses it when you click a session under Remote Machines — on Linux it opens your terminal emulator running this command, on macOS a .command file that Terminal runs, on Windows a wt/cmd window. You'll rarely type it yourself, but it's handy if the tray can't find a terminal emulator and prints the command for you to run.

Windows

All four commands work with tyoreach.exe from PowerShell or cmd. Two differences: Windows hosts always serve fresh shells (there's no tmux-style reattach for cmd or PowerShell — use WSL + tmux for that, see Reach Sessions), and the terminal size is sent once at attach time rather than tracking live resizes.

Common questions

Do I need the proxy switched on to use sessions?

No. Sessions use their own tunnel to the gateway and work whether Proxy is on or off.

Can I attach to a session someone else is already in?

Yes — multiple viewers can attach to the same session; reach sessions shows the count. Whether you can type depends on the access the host granted you.

Why does reach sessions say "No session hosts online" when my other PC is on?

The other PC must be hosting: either Host sessions on this PC in its tray or a running reach host. Being signed in isn't enough by itself.