Remote Observation

hty’s $HTY_SOCKET environment variable lets you point any hty client at a remote server’s Unix socket forwarded over SSH. With a single SSH tunnel, you can list sessions, watch them in real time, attach interactively, or drive them with hty send and hty wait — all from your local machine.

How it works

By default, each hty client resolves the socket path from $XDG_RUNTIME_DIR/hty/sock, falling back to ~/.local/state/hty/sock. When $HTY_SOCKET is set to any non-empty value, the client uses that path instead and skips the auto-spawn logic entirely.

This means:

• When $HTY_SOCKET is set, the client never auto-spawns a local server
• If the socket at that path is not reachable, the client fails immediately
• There is no silent fallback to a local server

This behavior is intentional. A broken tunnel fails fast and loudly, so you always know whether you’re operating on the remote server or not.

Step-by-step setup

1. Start a session on the remote machine

SSH into the remote host and start an hty session:

# On the remote machine
hty run --name foo -- vim /tmp/bar.txt

The session runs in the remote hty server. You can disconnect your SSH shell — the session persists.

2. Find the remote socket path

Run hty info on the remote machine to see the socket path:

$ hty info
hty v0.5.0
socket:  /run/user/1000/hty/sock
logs:    /home/user/.local/state/hty/logs
server:  running

For scripted tunnel setup, use --json and jq so you don’t have to hardcode the path:

REMOTE_SOCK=$(ssh user@remote-host hty info --json | jq -r .socket_path)

3. Open an SSH tunnel

From your laptop, forward the remote Unix socket to a local path:

ssh -L "/tmp/hty-remote.sock:${REMOTE_SOCK}" user@remote-host
# or, with a hardcoded path:
ssh -L /tmp/hty-remote.sock:/run/user/1000/hty/sock user@remote-host

Keep this SSH connection open — the tunnel only exists while the connection is active.

4. Connect your local hty to the remote server

In a new terminal on your laptop, set HTY_SOCKET and run hty commands as usual:

export HTY_SOCKET=/tmp/hty-remote.sock
hty list          # see remote sessions
hty watch foo     # watch the remote session live (read-only)
hty attach foo    # attach bidirectionally

All hty commands in this shell now target the remote server.

Watching a CI session remotely

If you’re running a long CI job on a remote machine and want to observe it from your laptop:

1. Ensure the CI job uses named sessions (hty run --name build -- ...)
2. Open an SSH tunnel to the CI machine as described above
3. Set HTY_SOCKET and run hty watch build

You’ll see the terminal output of the running CI session in real time. Press Ctrl+C to stop watching — the remote session continues unaffected.

hty watch will also wait for a named session that doesn’t exist yet: you can start the watcher on your laptop first (through the tunnel) and then kick off the remote job, and watch starts streaming the moment that session spawns. This removes the “did I start the watcher in time?” race when demoing a run.