사용 가이드

SessionCast를 효과적으로 사용하는 방법을 알아봅니다.

시작하기

기본 워크플로우

1

tmux 세션 생성

로컬 머신에서 tmux 세션을 생성합니다.

tmux new -s workspace
2

Agent 확인

Agent가 실행 중이면 자동으로 세션이 감지됩니다.

# 데몬 상태 확인
sessioncast daemon status

# 에이전트 로그 확인
sessioncast daemon logs

# "Session 'workspace' registered" 출력 확인
3

웹에서 접속

브라우저에서 SessionCast 웹에 접속하고 Google 계정으로 로그인합니다.

4

세션 선택 및 사용

세션 목록에서 원하는 세션을 클릭하면 터미널이 표시됩니다.

tmux 세션

세션 생성

tmux 기본 명령어 
# 새 세션 생성
tmux new -s session-name

# 백그라운드로 세션 생성
tmux new -d -s session-name

# 세션에 창(window) 추가
tmux new-window -t session-name

# 세션 목록 확인
tmux ls

세션 이름 규칙

SessionCast에서 세션은 machineId/tmuxSession 형식으로 식별됩니다:

  • my-workstation/dev - my-workstation 머신의 dev 세션
  • server-01/monitoring - server-01 머신의 monitoring 세션

Auto-Discovery 모드

autoDiscovery: true를 설정하면 Agent가 자동으로 모든 tmux 세션을 감지합니다:

# ~/.sessioncast.yml
machineId: my-workstation
relay: wss://relay.sessioncast.io/ws
token: agt_your_token
autoDiscovery: true

Auto-Discovery 제외

특정 세션을 제외하려면 세션 이름 앞에 _ (언더스코어)를 붙이세요:

tmux new -s _private-session

웹 인터페이스

로그인

SessionCast는 Google OAuth 2.0을 사용합니다:

  1. 웹 페이지에서 "Sign in with Google" 버튼 클릭
  2. Google 계정 선택 및 인증
  3. 자동으로 세션 목록 페이지로 이동

도메인 제한

관리자가 ALLOWED_DOMAINS를 설정한 경우, 해당 도메인의 이메일만 접속할 수 있습니다.

세션 목록

로그인 후 자신의 Agent Token으로 등록된 세션만 표시됩니다:

  • 세션 라벨: 설정된 라벨 또는 tmux 세션 이름
  • 머신 ID: 세션이 실행 중인 머신
  • 상태 표시: 연결됨/연결 해제됨

터미널 뷰

세션을 클릭하면 터미널 화면이 표시됩니다:

  • 실시간 화면: tmux 세션의 현재 상태
  • 자동 리사이징: 브라우저 창 크기에 맞게 터미널 크기 조절
  • 컬러 지원: ANSI 이스케이프 코드를 통한 컬러 출력

키보드 입력

기본 입력

터미널 영역을 클릭한 후 키보드 입력이 가능합니다:

  • 일반 텍스트 입력
  • Enter 키로 명령 실행
  • 방향키, Backspace, Delete 등 특수 키

Control 키 조합

키 기능
Ctrl + C 현재 프로세스 중단 (SIGINT)
Ctrl + D EOF 전송 / 쉘 종료
Ctrl + Z 프로세스 일시 중지 (SIGTSTP)
Ctrl + L 화면 지우기
Ctrl + A 줄 시작으로 이동
Ctrl + E 줄 끝으로 이동

tmux 프리픽스 키

tmux의 기본 프리픽스 키는 Ctrl + B입니다:

키 조합 기능
Ctrl+B → c 새 창(window) 생성
Ctrl+B → n 다음 창으로 이동
Ctrl+B → p 이전 창으로 이동
Ctrl+B → % 수직 분할
Ctrl+B → " 수평 분할
Ctrl+B → d 세션에서 분리 (detach)

주의사항

일부 브라우저 단축키와 충돌할 수 있습니다. 예: Ctrl+W는 브라우저에서 탭을 닫습니다. 이러한 키는 터미널로 전달되지 않을 수 있습니다.

세션 관리

웹에서 세션 생성

Web UI에서 새로운 tmux 세션을 생성할 수 있습니다:

  1. 세션 목록 화면에서 "New Session" 버튼 클릭
  2. 머신 선택
  3. 세션 이름 입력
  4. "Create" 버튼 클릭

Agent가 요청을 받아 로컬에서 tmux 세션을 생성합니다.

세션 종료

세션을 종료하는 방법:

  • 웹 UI: 세션 목록에서 삭제 버튼 클릭
  • 터미널: exit 명령 또는 Ctrl+D
  • tmux 명령: tmux kill-session -t session-name

세션 목록 새로고침

세션 목록은 자동으로 업데이트되지만, 수동으로 새로고침하려면:

  • 세션 목록 화면에서 새로고침 버튼 클릭
  • 브라우저 새로고침 (F5)

문제 해결

세션이 목록에 표시되지 않음

확인사항:

  1. Agent가 실행 중인지 확인 
    sessioncast daemon status
  2. Agent 로그 확인 
    sessioncast daemon logs
  3. tmux 세션이 존재하는지 확인 
    tmux ls
  4. Agent Token이 올바른지 확인
  5. 웹에서 로그인한 이메일이 Token의 owner와 일치하는지 확인

화면이 비어있음

원인:

새로 생성된 tmux 세션은 아직 어떤 명령도 실행되지 않아 빈 화면일 수 있습니다.

해결:

  1. 터미널에서 직접 세션에 접속하여 명령 실행 
    tmux attach -t session-name
  2. 또는 웹에서 아무 키나 입력하여 화면 갱신 유도

키 입력이 전달되지 않음

확인사항:

  1. 터미널 영역을 클릭하여 포커스가 있는지 확인
  2. 브라우저 개발자 도구에서 WebSocket 연결 상태 확인
  3. Agent 로그에서 키 수신 메시지 확인

연결이 자주 끊김

가능한 원인:

  • 네트워크 불안정
  • 프록시/방화벽 WebSocket 차단
  • 서버 리소스 부족

해결:

  1. 네트워크 연결 상태 확인
  2. 프록시 설정에서 WebSocket 허용 확인
  3. 서버 로그 확인: 
    journalctl -u sessioncast -f

에이전트 재시작

데몬 (권장) 
# 데몬 재시작
sessioncast daemon stop
sessioncast daemon start

# 상태 확인
sessioncast daemon status

# 로그 확인
sessioncast daemon logs
포그라운드 (디버깅용) 
# 포그라운드로 실행하여 실시간 출력 확인
sessioncast agent