설치

바이너리 하나를 받아 ~/.local/bin 에 둡니다.

플랫폼 고르기

brew trust --tap sophonz-labs/tap
brew install sophonz-labs/tap/st

Homebrew는 자기 것이 아닌 tap을 불러오기 전에 확인을 받으므로 brew trust를 먼저 실행합니다.

Homebrew 없이:

curl -fsSL https://dl.sophonz.io/install.sh | sh

~/.local/bin/st 에 설치됩니다 (Homebrew는 자기 prefix에 둡니다). ~/.local/bin 이 PATH에 없으면 스크립트가 쓰는 셸에 맞는 추가 방법을 알려줍니다.

macOS 13 이상에서 실행됩니다. 함께 담긴 tmux와 ttyd도 마찬가지입니다.

Intel Mac용 빌드는 배포하지 않습니다. 만들려면 Intel Mac이 있어야 하고, 그 머신의 st 소스 체크아웃에서 make build를 실행하면 dist/st가 만들어집니다.

어느 경로든 설치되는 것은 바이너리 하나이고, 필요한 것은 그 안에 들어 있습니다 — ttyd, 멀티플렉서, 웹 자산과 폰트. 미리 깔 것이 없습니다.

함께 설치되는 것

어디서 오나
ttyd바이너리 안
tmux설치돼 있으면 그것, 없으면 바이너리 안
zellij바이너리 안
psmux (Windows)설치돼 있으면 그것, 없으면 바이너리 안
웹 자산과 폰트바이너리 안
cloudflared터널을 처음 쓸 때 한 번 내려받습니다

tmux가 있는 곳에서는 tmux를 씁니다. 두 브라우저가 한 세션의 서로 다른 창에 동시에 붙을 수 있는 쪽은 tmux뿐입니다. 순서는 설치된 것이 먼저라, 내 tmux에서 이미 실행 중인 세션에 그대로 들어갑니다. 동봉본은 tmux가 아예 없는 장치를 위한 것입니다. Windows만 예외로, 네이티브 tmux가 없어 psmux가 그 자리를 대신합니다.

cloudflared는 ~/.sophonz/bin 에 버전과 SHA-256을 고정해 한 번 내려받고, st --no-tunnel 로 쓰는 경우에는 아예 필요하지 않습니다.

다른 위치에, 다른 버전으로

curl -fsSL https://dl.sophonz.io/install.sh | ST_INSTALL_DIR=/usr/local/bin sh
curl -fsSL https://dl.sophonz.io/install.sh | ST_VERSION=v0.3.116 sh

Windows

st.exe는 %LOCALAPPDATA%\Programs\sophonz 에 설치되고 그 경로가 PATH에 추가됩니다. 지금 쓰고 있는 셸을 그대로 공유하며(기본은 PowerShell, st --command cmd.exe 로 바꿀 수 있습니다), 터널과 브라우저 쪽은 다른 플랫폼과 같습니다.

tmux가 아니라 psmux입니다. Windows에는 네이티브 tmux가 없어서, 브라우저가 떠나도 세션을 들고 있는 쪽은 psmux입니다. ConPTY 위에서 네이티브로 실행되고 tmux 명령을 알아듣는 Windows용 tmux이고, 없으면 zellij로 갑니다(--mux zellij). psmux에는 세션 그룹이 없어서 두 브라우저가 한 세션에서 같은 창을 보게 됩니다.

PATH에 tmux 가 있어도 쓰지 않습니다. Windows용으로 패키징된 tmux는 Cygwin 빌드라 네이티브 Windows 콘솔 프로그램을 구동하지 못합니다.

WSL은 또 하나의 길이고, 설치 줄은 위 탭에 있습니다. 그 안은 리눅스라 — linux-x64 빌드에 배포판의 tmux — 거기서 띄운 세션은 PowerShell이 아니라 리눅스 세션입니다.

갱신

st upgrade

설치 스크립트를 이 바이너리가 있는 디렉터리에 대해 다시 실행합니다. 다른 곳에 설치했다면 그 자리에 덮어씁니다.

새 버전으로 바꾼 뒤에는 이전 버전 이후 달라진 점을 보여 줍니다(st 0.3.78 이상). 릴리스별로 최신순으로 바뀐 점을 나열하고, 건너뛴 버전이 많으면 최근 여덟 개만 보여 준 뒤 나머지는 다운로드에서 보도록 안내합니다.

Homebrew로 설치했다면 파일은 Homebrew의 것입니다. brew upgrade st 다음에 st restart로 공유를 새 버전으로 옮깁니다. st upgrade는 Homebrew의 사본을 덮어쓰지 않고 그렇게 안내합니다.

폰에서. 장치의 st에 업데이트가 있으면 앱이 그 장치에 "업데이트 있음"을 보여 줍니다. st 업데이트는 그 장치에서 st upgrade와 똑같은 일을 하고 단계마다 보여 줍니다. 링크는 그대로이고 세션도 계속 실행됩니다. 새 버전이 1분 30초 안에 같은 터널로 답하지 않으면 쓰던 버전을 제자리에 돌려놓고 공유도 그쪽으로 돌아갑니다. Homebrew로 설치한 장치, 그리고 로그인하지 않고 터널을 쓰는 장치(주소가 유일한 접속 경로)에는 나오지 않습니다. 처음에는 다른 방법으로도 접속할 수 있는 장치에서 해 보세요.

데스크탑 앱에서(0.1.32 이상). st가 최신 버전이 아닌 장치는 사이드바의 장치 행에 ↑ v…가 붙습니다. 이 장치와 다른 장치 모두 마찬가지이고, 행을 오른쪽 클릭한 메뉴에도 Update st to v…가 있습니다. 실행하면 먼저 확인을 받고, 그 장치의 버전 이후 바뀐 점을 보여 준 다음 진행 단계를 행에 표시합니다. 동작은 폰의 st 업데이트와 같고, 메뉴가 나오지 않는 경우도 같습니다.

갱신은 실행 중인 공유를 내리지 않습니다:

  • 새 바이너리가 먼저 스스로를 점검합니다 — ttyd가 뜨고 페이지를 내주는지. 실행 중인 에이전트에게는 그다음에야 묻습니다. 점검에 실패하면 쓰던 버전을 제자리에 돌려놓고, 공유는 건드리지 않습니다.
  • 옛 에이전트가 물러난 뒤 새 에이전트가 끝내 뜨지 않으면, 방금까지 실행 중이던 버전이 같은 포트와 터널을 다시 잡습니다.
  • 이 장치에서 공유를 띄운 적 있는 버전은 ~/.sophonz/bin 에 보관됩니다(최근 세 개). 시작할 때 자가 점검에 실패하면 st 는 보관된 것 중 여기서 동작하는 가장 최근 버전으로 대신 띄웁니다.
st rollback           # 이전 버전을 제자리에 돌려놓고 공유를 그쪽으로 옮김

Windows

윈도우도 st 0.3.73부터 같은 방식으로 공유를 넘겨줍니다. st upgrade 가 공유를 새 바이너리로 옮기고 주소는 그대로입니다. 넘겨줄 수 없는 것은 그보다 오래된 st가 띄운 공유뿐입니다. 그 터널은 옛 에이전트와 함께 닫히기 때문입니다. 그런 공유에서는 st upgrade 가 새 바이너리를 설치하고, 공유는 옛 버전에 둔 채 still sharing on the old version — st restart moves it over 를 알립니다.

st restart            # 공유를 내렸다가 이 바이너리로 다시 띄움

st restart 가 그 자리를 메웁니다. st exit 다음에 st 가 아니라 이것 하나만 실행합니다. 둘로 나누면 뒷절반을 실행할 다른 통로가 필요한데, 이 공유로만 닿는 장치에는 그런 통로가 없습니다.

지켜지는 것:

  • 세션. 세션과 그 안에서 실행 중이던 것들은 그대로 남습니다.
  • 포트와 토큰. 토큰이 그대로라 토큰 링크는 새 주소에서도 같은 토큰으로 열립니다.
  • 계정의 링크. 로그인된 장치라면 slug는 터널과 상관없이 장치에 붙어 있어 그대로입니다.

st 0.3.73 이전에 띄운 공유에서 지켜지지 않는 것은 trycloudflare.com 주소뿐입니다. cloudflared가 새로 뜨면 주소도 새로 생기고, st restart 가 그 주소를 출력합니다. 0.3.73부터, 그리고 macOS와 Linux에서는 잃을 것이 없습니다. 터널을 이어받으므로 주소가 그대로입니다.

로그인하지 않았다면, 주소가 전부입니다

계정의 링크가 있으면 주소를 버려도 됩니다. 계정이 없으면 그 링크가 없고, st 0.3.73 이전에 띄운 윈도우 공유를 재시작하면 이 공유로만 닿는 장치에 다시 들어갈 수 없게 됩니다:

  • 옛 주소는 에이전트가 내려가는 순간 죽고
  • 새 주소는 세션 안에 찍히는데 — 옛 주소로 붙어 있던 브라우저는 그 세션에 더는 닿을 수 없고
  • 장치가 어디로 갔는지 아는 곳이 아무 데도 없습니다.

st restart 는 이 일이 확실히 일어날 때 그 사실을 알리고 진행 여부를 묻습니다. 거기서 st login 으로 답하세요. 장치가 고정 링크를 갖게 되고, 그 아래 주소는 얼마든지 바뀌어도 됩니다.

st login              # 장치당 한 번
st restart

로그인한 상태라면 어디서도 이 이야기는 해당되지 않습니다 — 링크는 그대로입니다.

공유 안의 PowerShell에서 갱신할 때

공유된 PowerShell 안에서 st upgrade 와 st restart 를 실행해도 됩니다. 이 공유로만 닿는 장치라면 거기서 실행하는 게 보통입니다. 순서는 이렇습니다.

st upgrade            # 새 바이너리만 설치합니다. 공유는 옛 버전으로 계속 실행됩니다
st restart            # 공유를 새 바이너리로 옮깁니다
  • st upgrade 는 실행 중인 st.exe 를 바꿔 놓습니다. 실행 중인 st.exe 는 덮어쓸 수 없어서 설치 스크립트가 옛 파일의 이름을 바꿔 두고 새 파일을 놓습니다. st 0.3.73 이상이 띄운 공유는 그다음 새 파일로 넘어갑니다. 그보다 오래된 st가 띄운 공유는 옛 버전으로 계속 실행되고, still sharing on the old version — st restart moves it over 가 나옵니다. 이어서 st restart 를 실행합니다.
  • st restart 는 v0.3.52부터 공유 안에서 안전합니다. 그 전 버전에서는 그 뒤로 여는 터미널마다 곧바로 "session ended"로 끝났습니다. st upgrade 를 먼저 하면 st restart 를 실행하는 쪽이 새 바이너리라 이 문제를 피합니다. 이미 이렇게 됐다면 공유 밖의 터미널(그 PC에서 직접 연 PowerShell, 원격 데스크톱)에서 st restart 를 한 번 더 실행합니다.
  • 오래된 공유를 재시작한 뒤에는 열려 있던 탭을 다시 엽니다. 주소가 바뀌므로 옛 주소에 붙어 있던 브라우저 탭은 다시 연결되지 않습니다. 계정의 링크로 다시 열면(대시보드나 앱에서도) 새 주소로 들어갑니다. 세션과 그 안의 프로그램은 그대로 있습니다.
  • st exit 와 Stop-Process -Name st 는 공유 안에서 실행하지 않습니다. 공유가 내려가면 다시 띄울 통로가 없습니다. 설치 스크립트가 st.exe 를 잡고 있는 프로세스 때문에 멈추면서 이 두 줄을 권할 때가 있는데(관리자 권한으로 띄운 st 등), 이건 그 PC 앞에서 할 일입니다.
  • --mux none 으로 띄운 공유는 셸이 남지 않습니다. 셸을 들고 있는 psmux가 없으니 재시작과 함께 셸도 끝납니다. 공유 자체는 다시 뜹니다.
  • PowerShell 7(pwsh)에서도 됩니다(v0.3.51부터). 그보다 오래된 st를 pwsh에서 갱신했다면 st --version 으로 버전이 실제로 바뀌었는지 확인합니다.
  • 윈도우에서도 새 바이너리의 ttyd를 미리 점검합니다(v0.3.53부터). 위의 자가 점검이 윈도우에서도 ttyd를 띄워 페이지를 받아 봅니다. 점검을 통과하지 못한 버전으로는 옮기지 않고 공유도 건드리지 않습니다. 점검은 새 바이너리가 하므로, v0.3.53 이후로 가는 갱신이면 어느 버전에서 올리든 적용됩니다.

공유를 계속 살려 두기

선택 사항입니다. st를 launchd(macOS)나 systemd --user(Linux)에 등록해, 로그인할 때와 공유가 꺼져 있을 때마다 다시 띄웁니다 — 크래시, 재부팅, 망가진 갱신 뒤에도(10분 안에 세 번 실패하면 보관된 이전 버전으로 띄움).

st service install [--session 이름] [--no-tunnel]
st service status
st service uninstall  # 공유 자체는 계속 실행됩니다

st exit 은 여전히 정지입니다. st 를 다시 실행하기 전까지 서비스가 되살리지 않습니다. 로그는 ~/.sophonz/keepalive.log 입니다.