Share a terminal

Run st and it prints an address and a QR code.

st

An agent starts in the background and the terminal comes straight back. What it prints is an address, a token, and a QR code carrying both.

Scan it, or open the link with the token once. The server swaps the token for a cookie on arrival and drops it from the address, so the secret stops travelling in URLs — and out of them into logs.

The QR code holds https://link.sophonz.io/j#<link with the token> rather than that link itself (st 0.3.72 and later). A phone with the sophonz app opens it in the app; one without opens the browser terminal. The link is after the #, which a browser never sends, so the token still goes only to your machine. SOPHONZ_QR_DIRECT=1 puts the link itself back in the QR, for a phone that cannot reach link.sophonz.io.

Output


`url`	the address Cloudflare handed out (or the machine's tailnet or relay address, see `st route`). A new one after `st exit` and `st`; `st restart` and `st upgrade` keep it
`token`	the shared secret for this session
`link`	only when signed in. This one does not change

Cloudflare's documentation says quick tunnels do not support Server-Sent Events. From st 0.3.67, st works around that, so agent state, chat and machine metrics arrive live over this address; with an older st the Cloudflare tunnel holds them back and they come late.

Pro: the sophonz relay

On the free plan, url is a Cloudflare quick tunnel address, and it is a new one each time you run st after st exit. Cloudflare offers it for testing and development, with no uptime guarantee; its limits are gathered in Ways to run. Pro includes a relay server run by sophonz. Through it the machine keeps one address of three words, such as https://quiet-otter-lamp.relay.sophonz.io, across restarts.

From st 0.4.1, a machine signed in to a Pro account fetches its relay address and token itself; there is nothing to type. On 0.4.0 or older, run st upgrade.

st relay         # which way this machine is reached now
st route relay   # pick the sophonz relay
st relay reset   # pick a Cloudflare quick tunnel and stay there

st relay reset drops a relay of your own and picks a quick tunnel. If you chose your tailnet with st route tailscale, that choice stays.

What you chose comes first. If you picked a quick tunnel or your tailnet with st route, or set a relay of your own with st relay set <relay address> --token <token>, st leaves it as it is. Leave out --token and st reads ST_RELAY_TOKEN, or asks for it. st relay and st route show the sophonz relay as sophonz's and never show its token.

When the Pro plan ends, the machine goes back to a quick tunnel.
A machine removed from the account signs out and stops sharing. Its terminal sessions stay.
After signing out, or signing in to another account, the machine no longer uses the relay it received for the previous account.
If the relay does not take the machine when it starts, it opens on a quick tunnel until its next report, and st route says why.

What has and has not been confirmed on a machine reached through the relay is in Ways to run.

The rest of it

st --session work     # share a named session
st --no-tunnel        # no public address; this machine only
st url                # print the link again
st ls                 # running sessions and who is on them
st exit               # stop sharing

st ls lists the running sessions with the devices on each, then the sessions on your other machines (st 0.3.98); st attach <machine>/<session> puts this terminal on one of those. Enter attaches to one, d disconnects a device (on a session, all of its devices), and r refreshes.